Skip to content
Back to search

mcp-server-milvus

Model Context Protocol Servers for Milvus

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zilliztech--mcp-server-milvus/badge.svg)](/listings/zilliztech--mcp-server-milvus)

HTML

<a href="/listings/zilliztech--mcp-server-milvus"><img src="/api/listings/zilliztech--mcp-server-milvus/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 500 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Server for Milvus
  2. > The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
  3. This repository contains a MCP server that provides access to [Milvus](https://milvus.io/) vector database functionality.
  4. ![MCP with Milvus](Claude_mcp+1080.gif)
  5. ## Prerequisites
  6. Before using this MCP server, ensure you have:
  7. - Python 3.10 or higher
  8. - A running [Milvus](https://milvus.io/) instance (local or remote)
  9. - [uv](https://github.com/astral-sh/uv) installed (recommended for running the server)
  10. ## Usage
  11. The recommended way to use this MCP server is to run it directly with `uv` without installation. This is how both Claude Desktop and Cursor are configured to use it in the examples below.
  12. If you want to clone the repository:
  13. ```bash
  14. git clone https://github.com/zilliztech/mcp-server-milvus.git
  15. cd mcp-server-milvus
  16. ```
  17. Then you can run the server directly:
  18. ```bash
  19. uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530
  20. ```
  21. Alternatively you can change the .env file in the `src/mcp_server_milvus/` directory to set the environment variables and run the server with the following command:
  22. ```bash
  23. uv run src/mcp_server_milvus/server.py
  24. ```
  25. ### Important: the .env file will have higher priority than the command line arguments.
  26. ### Running Modes
  27. The server supports two running modes: **stdio** (default) and **SSE** (Server-Sent Events).
  28. ### Stdio Mode (Default)
  29. - **Description**: Communicates with the client via standard input/output. This is the default mode if no mode is specified.
  30. - Usage:
  31. ```bash
  32. uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530
  33. ```
  34. ### SSE Mode
  35. - **Description**: Uses HTTP Server-Sent Events for communication. This mode allows multiple clients to connect via HTTP and is suitable for web-based applications.
  36. - **Usage:**
  37. ```bash
  38. uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
  39. ```
  40. - `--sse`: Enables SSE mode.
  41. - `--port`: Specifies the port for the SSE server (default: 8000).
  42. - **Debugging in SSE Mode:**
  43. If you want to debug in SSE mode, after starting the SSE service, enter the following command:
  44. ```bash
  45. mcp dev src/mcp_server_milvus/server.py
  46. ```
  47. The output will be similar to:
  48. ```plaintext
  49. % mcp dev src/mcp_server_milvus/merged_server.py
  50. Starting MCP inspector...
  51. ⚙️ Proxy server listening on port 6277
  52. 🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
  53. ```
  54. You can then access the MCP Inspector at `http://127.0.0.1:6274` for testing.
  55. ### Streamable HTTP Mode
  56. - **Description**: Uses HTTP with streaming support for communication. This is the recommended transport for production deployments and supports both stateful and stateless operation.
  57. - **Usage:**
  58. ```bash
  59. uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
  60. ```
  61. - `--streamable-http`: Enables Streamable HTTP mode.
  62. - `--port`: Specifies the port for the server (default: 8000).
  63. - `--stateless`: Optional flag for stateless mode (no session persistence).
  64. - **Stateless Mode:**
  65. ```bash
  66. uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000
  67. ```
  68. ## Supported Applications
  69. This MCP server can be used with various LLM applications that support the Model Context Protocol:
  70. - **Claude Desktop**: Anthropic's desktop application for Claude
  71. - **Cursor**: AI-powered code editor with MCP support
  72. - **Custom MCP clients**: Any application implementing the MCP client specification
  73. ## Usage with Claude Desktop
  74. ### Configuration for Different Modes
  75. #### SSE Mode Configuration
  76. Follow these steps to configure Claude Desktop for SSE mode:
  77. 1. Install Claude Desktop from https://claude.ai/download.
  78. 2. Open your Claude Desktop configuration file:
  79. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  80. 3. Add the following configuration for SSE mode:
  81. ```json
  82. {
  83. "mcpServers": {
  84. "milvus-sse": {
  85. "url": "http://your_sse_host:port/sse",
  86. "disabled": false,
  87. "autoApprove": []
  88. }
  89. }
  90. }
  91. ```
  92. #### Streamable HTTP Mode Configuration
  93. ```json
  94. {
  95. "mcpServers": {
  96. "milvus-streamable-http": {
  97. "url": "http://your_host:port/mcp",
  98. "disabled": false,
  99. "autoApprove": []
  100. }
  101. }
  102. }
  103. ```
  104. 4. Restart Claude Desktop to apply the changes.
  105. #### Stdio Mode Configuration
  106. For stdio mode, follow these steps:
  107. 1. Install Claude Desktop from https://claude.ai/download.
  108. 2. Open your Claude Desktop configuration file:
  109. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  110. 3. Add the following configuration for stdio mode:
  111. ```json
  112. {
  113. "mcpServers": {
  114. "milvus": {
  115. "command": "/PATH/TO/uv",
  116. "args": [
  117. "--directory",
  118. "/path/to/mcp-server-milvus/src/mcp_server_milvus",
  119. "run",
  120. "server.py",
  121. "--milvus-uri",
  122. "http://localhost:19530"
  123. ]
  124. }
  125. }
  126. }
  127. ```
  128. 4. Restart Claude Desktop to apply the changes.
  129. ## Usage with Cursor
  130. [Cursor also supports MCP](https://docs.cursor.com/context/model-context-protocol) tools. You can integrate your Milvus MCP server with Cursor by following these steps:
  131. ### Integration Steps
  132. 1. Open `Cursor Settings` > `MCP`
  133. 2. Click on `Add new global MCP server`
  134. 3. After clicking, it will automatically redirect you to the `mcp.json` file, which will be created if it doesn’t exist
  135. ### Configuring the `mcp.json` File
  136. #### For Stdio Mode:
  137. Overwrite the `mcp.json` file with the following content:
  138. ```json
  139. {
  140. "mcpServers": {
  141. "milvus": {
  142. "command": "/PATH/TO/uv",
  143. "args": [
  144. "--directory",
  145. "/path/to/mcp-server-milvus/src/mcp_server_milvus",
  146. "run",
  147. "server.py",
  148. "--milvus-uri",
  149. "http://127.0.0.1:19530"
  150. ]
  151. }
  152. }
  153. }
  154. ```
  155. #### For SSE Mode:
  156. 1. Start the service by running the following command:
  157. ```bash
  158. uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
  159. ```
  160. > **Note**: Replace `http://your_sse_host` with your actual SSE host address and `port` with the specific port number you’re using.
  161. 2. Once the service is up and running, overwrite the `mcp.json` file with the following content:
  162. ```json
  163. {
  164. "mcpServers": {
  165. "milvus-sse": {
  166. "url": "http://your_sse_host:port/sse",
  167. "disabled": false,
  168. "autoApprove": []
  169. }
  170. }
  171. }
  172. ```
  173. #### For Streamable HTTP Mode:
  174. 1. Start the service:
  175. ```bash
  176. uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port
  177. ```
  178. 2. Update `mcp.json`:
  179. ```json
  180. {
  181. "mcpServers": {
  182. "milvus-streamable-http": {
  183. "url": "http://your_host:port/mcp",
  184. "disabled": false,
  185. "autoApprove": []
  186. }
  187. }
  188. }
  189. ```
  190. ### Completing the Integration
  191. After completing the above steps, restart Cursor or reload the window to ensure the configuration takes effect.
  192. ## Verifying the Integration
  193. To verify that Cursor has successfully integrated with your Milvus MCP server:
  194. 1. Open `Cursor Settings` > `MCP`
  195. 2. Check if "milvus", "milvus-sse", or "milvus-streamable-http" appear in the list (depending on the mode you have chosen)
  196. 3. Confirm that the relevant tools are listed (e.g., milvus_list_collections, milvus_vector_search, etc.)
  197. 4. If the server is enabled but shows an error, check the Troubleshooting section below
  198. ## Available Tools
  199. The server provides the following tools:
  200. ### Search and Query Operations
  201. - `milvus_text_search`: Search for documents using full text search
  202. - Parameters:
  203. - `collection_name`: Name of collection to search
  204. - `query_text`: Text to search for
  205. - `limit`: The maximum number of results to return (default: 5)
  206. - `output_fields`: Fields to include in results
  207. - `drop_ratio`: Proportion of low-frequency terms to ignore (0.0-1.0) (default: 0.2)
  208. - `milvus_vector_search`: Perform vector similarity search on a collection
  209. - Parameters:
  210. - `collection_name`: Name of collection to search
  211. - `vector`: Query vector
  212. - `vector_field`: Field name for vector search (default: "vector")
  213. - `limit`: The maximum number of results to return (default: 5)
  214. - `output_fields`: Fields to include in results
  215. - `filter_expr`: Filter expression
  216. - `metric_type`: Distance metric (COSINE, L2, IP) (default: "COSINE")
  217. - `radius`: Optional lower bound for range search (default: None)
  218. - `range_filter`: Optional upper bound for range search (default: None)
  219. - `milvus_hybrid_search`: Perform hybrid search on a collection
  220. - Parameters:
  221. - `collection_name`: Name of collection to search
  222. - `query_text`: Text query for search
  223. - `text_field`: Field name for text search
  224. - `vector`: Vector of the text query
  225. - `vector_field`: Field name for vector search
  226. - `limit`: The maximum number of results to return (default: 5)
  227. - `output_fields`: Fields to include in results
  228. - `filter_expr`: Filter expression
  229. - `sparse_radius`: Optional lower bound for sparse range search (default: None)
  230. - `sparse_range_filter`: Optional upper bound for sparse range search (default: None)
  231. - `dense_radius`: Optional lower bound for dense range search (default: None)
  232. - `dense_range_filter`: Optional upper bound for dense range search (default: None)
  233. - `milvus_text_similarity_search`: Perform text similarity search on a collection
  234. > **Note**: This tool is only supported in Milvus 2.6.0 and above. And you need to set the embedding function at the Milvus server. See [Embedding Function](https://milvus.io/docs/embedding-function-overview.md#Embedding-Function-Overview) for more details.
  235. - Parameters:
  236. - `collection_name`: Name of collection to search
  237. - `query_text`: Text query for similarity search
  238. - `anns_field`: Field name for text search
  239. - `limit`: The maximum number of results to return (default: 5)
  240. - `output_fields`: Fields to include in results
  241. - `metric_type`: Distance metric (COSINE, L2, IP) (default: "COSINE")
  242. - `filter_expr`: Optional filter expression
  243. - `radius`: Optional lower bound for range search (default: None)
  244. - `range_filter`: Optional upper bound for range search (default: None)
  245. - `milvus_query`: Query collection using filter expressions
  246. - Parameters:
  247. - `collection_name`: Name of collection to query
  248. - `filter_expr`: Filter expression (e.g. 'age > 20')
  249. - `output_fields`: Fields to include in results
  250. - `limit`: The maximum number of results to return (default: 10)
  251. ### Collection Management
  252. - `milvus_list_collections`: List all collections in the database
  253. - `milvus_create_collection`: Create a new collection with quick setup or customized schema
  254. - Parameters:
  255. - `collection_name`: Name for the new collection
  256. - `auto_id`: whether to auto generate id, default to True
  257. - `dimension`: vector dimension, default to 768; for quick setup and will be ignored if `field_schema` is provided
  258. - `primary_field_name`: name of the primary field, default to "id"; for quick setup and will be ignored if `field_schema` is provided
  259. - `vector_field_name`: name of the vector field, default to "vector"; for quick setup and will be ignored if `field_schema` is provided
  260. - `metric_type`: metric type, default to "COSINE"; for quick setup and will be ignored if `field_schema` is provided
  261. - `field_schema`: List of field schema, each element is a dictionary with the following keys:
  262. - `name`: name of the field
  263. - `type`: type of the field
  264. - `index_params`: Optional list of index parameters, each element is a dictionary with the following keys:
  265. - `field_name`: name of the field to index
  266. - `index_type`: index type
  267. - `**kwargs`: other optional index parameters
  268. - `other_kwargs`: Additional keyword arguments for the collection creation
  269. - `milvus_load_collection`: Load a collection into memory for search and query
  270. - Parameters:
  271. - `collection_name`: Name of collection to load
  272. - `replica_number`: Number of replicas (default: 1)
  273. - `milvus_release_collection`: Release a collection from memory
  274. - Parameters:
  275. - `collection_name`: Name of collection to release
  276. - `milvus_get_collection_info`: Lists detailed information like schema, properties, collection ID, and other metadata of a specific collection.
  277. - Parameters:
  278. - `collection_name`: Name of the collection to get detailed information about
  279. ### Data Operations
  280. - `milvus_insert_data`: Insert data into a collection
  281. - Parameters:
  282. - `collection_name`: Name of collection
  283. - `data`: Dictionary mapping field names to lists of values
  284. - `milvus_delete_entities`: Delete entities from a collection based on filter expression
  285. - Parameters:
  286. - `collection_name`: Name of collection
  287. - `filter_expr`: Filter expression to select entities to delete
  288. ## Environment Variables
  289. - `MILVUS_URI`: Milvus server URI (can be set instead of --milvus-uri)
  290. - `MILVUS_TOKEN`: Optional authentication token
  291. - `MILVUS_DB`: Database name (defaults to "default")
  292. ## Development
  293. To run the server directly:
  294. ```bash
  295. uv run server.py --milvus-uri http://localhost:19530
  296. ```
  297. ## Examples
  298. ### Using Claude Desktop
  299. #### Example 1: Listing Collections
  300. ```
  301. What are the collections I have in my Milvus DB?
  302. ```
  303. Claude will then use MCP to check this information on your Milvus DB.
  304. ```
  305. I'll check what collections are available in your Milvus database.
  306. Here are the collections in your Milvus database:
  307. 1. rag_demo
  308. 2. test
  309. 3. chat_messages
  310. 4. text_collection
  311. 5. image_collection
  312. 6. customized_setup
  313. 7. streaming_rag_demo
  314. ```
  315. #### Example 2: Searching for Documents
  316. ```
  317. Find documents in my text_collection that mention "machine learning"
  318. ```
  319. Claude will use the full-text search capabilities of Milvus to find relevant documents:
  320. ```
  321. I'll search for documents about machine learning in your text_collection.
  322. > View result from milvus-text-search from milvus (local)
  323. Here are the documents I found that mention machine learning:
  324. [Results will appear here based on your actual data]
  325. ```
  326. ### Using Cursor
  327. #### Example: Creating a Collection
  328. In Cursor, you can ask:
  329. ```
  330. Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)
  331. ```
  332. Cursor will use the MCP server to execute this operation:
  333. ```
  334. I'll create a new collection called 'articles' with the specified fields.
  335. Collection 'articles' has been created successfully with the following schema:
  336. - title: string
  337. - content: string
  338. - vector: float vector[128]
  339. ```
  340. ## Troubleshooting
  341. ### Common Issues
  342. #### Connection Errors
  343. If you see errors like "Failed to connect to Milvus server":
  344. 1. Verify your Milvus instance is running: `docker ps` (if using Docker)
  345. 2. Check the URI is correct in your configuration
  346. 3. Ensure there are no firewall rules blocking the connection
  347. 4. Try using `127.0.0.1` instead of `localhost` in the URI
  348. #### Authentication Issues
  349. If you see authentication errors:
  350. 1. Verify your `MILVUS_TOKEN` is correct
  351. 2. Check if your Milvus instance requires authentication
  352. 3. Ensure you have the correct permissions for the operations you're trying to perform
  353. #### Tool Not Found
  354. If the MCP tools don't appear in Claude Desktop or Cursor:
  355. 1. Restart the application
  356. 2. Check the server logs for any errors
  357. 3. Verify the MCP server is running correctly
  358. 4. Press the refresh button in the MCP settings (for Cursor)
  359. ### Getting Help
  360. If you continue to experience issues:
  361. 1. Check the [GitHub Issues](https://github.com/zilliztech/mcp-server-milvus/issues) for similar problems
  362. 2. Join the [Milvus Community Discord](https://milvus.io/discord) for support
  363. 3. File a new issue with detailed information about your problem

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.