MCP Server for Milvus

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