Skip to content

Commit 4b404ca

Browse files
zc277584121zc277584121
authored
Merge pull request #1506 from jinhonglin-ryan/master
finished milvus and mcp tutorial
2 parents 6a7ae9e + 8d37fc0 commit 4b404ca

File tree

1 file changed

+275
-0
lines changed

1 file changed

+275
-0
lines changed

‎bootcamp/tutorials/integration/milvus_and_mcp.md

+275
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,275 @@
1+
2+
3+
# **MCP + Milvus: Connecting AI with Vector Databases**
4+
5+
## **Introduction**
6+
The **Model Context Protocol (MCP)** is an open protocol that enables AI applications, such as Claude and Cursor, to interact with external data sources and tools seamlessly. Whether you're building custom AI applications, integrating AI workflows, or enhancing chat interfaces, MCP provides a standardized way to connect large language models (LLMs) with relevant contextual data.
7+
8+
9+
This tutorial walks you through **setting up an MCP server for Milvus**, allowing AI applications to perform vector searches, manage collections, and retrieve data using **natural language commands**—without writing custom database queries.
10+
11+
12+
## **Prerequisites**
13+
Before setting up the MCP server, ensure you have:
14+
15+
- Python 3.10 or higher
16+
- A running [Milvus](https://milvus.io/) instance
17+
- [uv](https://github.com/astral-sh/uv) (recommended for running the server)
18+
19+
20+
## **Getting Started**
21+
22+
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.
23+
24+
If you want to clone the repository:
25+
26+
```bash
27+
git clone https://github.com/zilliztech/mcp-server-milvus.git
28+
cd mcp-server-milvus
29+
```
30+
31+
Then you can run the server directly:
32+
33+
```bash
34+
uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530
35+
```
36+
37+
38+
## **Supported Applications**
39+
This MCP server can be used with various AI applications that support the Model Context Protocol, such as:
40+
41+
- **Claude Desktop**: Anthropic's desktop application for Claude
42+
- **Cursor**: AI-powered code editor with MCP support in its Composer feature
43+
- **Other custom MCP clients** Any application implementing the MCP client specification
44+
45+
46+
47+
## **Using MCP with Claude Desktop**
48+
49+
1. Install [Claude Desktop](https://claude.ai/download).
50+
2. Open the Claude configuration file:
51+
- On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
52+
3. Add the following configuration:
53+
```json
54+
{
55+
"mcpServers": {
56+
"milvus": {
57+
"command": "/PATH/TO/uv",
58+
"args": [
59+
"--directory",
60+
"/path/to/mcp-server-milvus/src/mcp_server_milvus",
61+
"run",
62+
"server.py",
63+
"--milvus-uri",
64+
"http://localhost:19530"
65+
]
66+
}
67+
}
68+
}
69+
```
70+
4. Restart Claude Desktop to apply the changes.
71+
72+
73+
74+
## **Using MCP with Cursor**
75+
[Cursor](https://docs.cursor.com/context/model-context-protocol) also supports MCP tools through its Agent feature in Composer. You can add the Milvus MCP server to Cursor in two ways:
76+
77+
### **Option 1: Using Cursor Settings UI**
78+
1. Open `Cursor Settings` → `Features` → `MCP`.
79+
2. Click `+ Add New MCP Server`.
80+
3. Fill in:
81+
- Type: `stdio`
82+
- Name: `milvus`
83+
- Command:
84+
```bash
85+
/PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530
86+
```
87+
- ⚠️ Tip: Use `127.0.0.1` instead of `localhost` to avoid potential DNS resolution issues.
88+
89+
### **Option 2: Using Project-specific Configuration (Recommended)**
90+
1. Create a `.cursor/mcp.json` file in your **project root directory**:
91+
```json
92+
{
93+
"mcpServers": {
94+
"milvus": {
95+
"command": "/PATH/TO/uv",
96+
"args": [
97+
"--directory",
98+
"/path/to/mcp-server-milvus/src/mcp_server_milvus",
99+
"run",
100+
"server.py",
101+
"--milvus-uri",
102+
"http://127.0.0.1:19530"
103+
]
104+
}
105+
}
106+
}
107+
```
108+
2. Restart Cursor to apply the configuration.
109+
110+
111+
After adding the server, you may need to press the refresh button in the MCP settings to populate the tool list. The Composer Agent will automatically use the Milvus tools when relevant to your queries.
112+
113+
114+
115+
116+
## **Verifying the Integration**
117+
To ensure the MCP server is correctly set up:
118+
119+
### **For Cursor**
120+
1. Go to `Cursor Settings` → `Features` → `MCP`.
121+
2. Confirm that `"Milvus"` appears in the list of MCP servers.
122+
3. Check if Milvus tools (e.g., `milvus_list_collections`, `milvus_vector_search`) are listed.
123+
4. If errors appear, see the **Troubleshooting** section below.
124+
125+
126+
## **MCP Server Tools for Milvus**
127+
This MCP server provides multiple tools for **searching, querying, and managing vector data in Milvus**. For more details, please refer to the [mcp-server-milvus](https://github.com/zilliztech/mcp-server-milvus) documentation.
128+
129+
### **🔍 Search and Query Tools**
130+
- **`milvus-text-search`** → Search for documents using full text search.
131+
- **`milvus-vector-search`** → Perform vector similarity search on a collection.
132+
- **`milvus-hybrid-search`** → Perform hybrid search combining vector similarity and attribute filtering.
133+
- **`milvus-multi-vector-search`** → Perform vector similarity search with multiple query vectors.
134+
- **`milvus-query`** → Query collection using filter expressions.
135+
- **`milvus-count`** → Count entities in a collection.
136+
137+
138+
### **📁 Collection Management**
139+
- **`milvus-list-collections`** → List all collections in the database.
140+
- **`milvus-collection-info`** → Get detailed information about a collection.
141+
- **`milvus-get-collection-stats`** → Get statistics about a collection.
142+
- **`milvus-create-collection`** → Create a new collection with specified schema.
143+
- **`milvus-load-collection`** → Load a collection into memory for search and query.
144+
- **`milvus-release-collection`** → Release a collection from memory.
145+
- **`milvus-get-query-segment-info`** → Get information about query segments.
146+
- **`milvus-get-collection-loading-progress`** → Get the loading progress of a collection.
147+
148+
### **📊 Data Operations**
149+
- **`milvus-insert-data`** → Insert data into a collection.
150+
- **`milvus-bulk-insert`** → Insert data in batches for better performance.
151+
- **`milvus-upsert-data`** → Upsert data into a collection (insert or update if exists).
152+
- **`milvus-delete-entities`** → Delete entities from a collection based on filter expression.
153+
- **`milvus-create-dynamic-field`** → Add a dynamic field to an existing collection.
154+
155+
### **⚙️ Index Management**
156+
- **`milvus-create-index`** → Create an index on a vector field.
157+
- **`milvus-get-index-info`** → Get information about indexes in a collection.
158+
159+
## **Environment Variables**
160+
- **`MILVUS_URI`** → Milvus server URI (can be set instead of `--milvus-uri`).
161+
- **`MILVUS_TOKEN`** → Optional authentication token.
162+
- **`MILVUS_DB`** → Database name (defaults to "default").
163+
164+
## **Development**
165+
To run the server directly:
166+
```bash
167+
uv run server.py --milvus-uri http://localhost:19530
168+
```
169+
170+
## **Examples**
171+
172+
### **Using Claude Desktop**
173+
174+
#### **Example 1: Listing Collections**
175+
176+
```
177+
What are the collections I have in my Milvus DB?
178+
```
179+
Claude will then use MCP to check this information on our Milvus DB.
180+
```
181+
I'll check what collections are available in your Milvus database.
182+
183+
> View result from milvus-list-collections from milvus (local)
184+
185+
Here are the collections in your Milvus database:
186+
187+
1. rag_demo
188+
2. test
189+
3. chat_messages
190+
4. text_collection
191+
5. image_collection
192+
6. customized_setup
193+
7. streaming_rag_demo
194+
```
195+
196+
#### **Example 2: Searching for Documents**
197+
198+
```
199+
Find documents in my text_collection that mention "machine learning"
200+
```
201+
202+
Claude will use the full-text search capabilities of Milvus to find relevant documents:
203+
204+
```
205+
I'll search for documents about machine learning in your text_collection.
206+
207+
> View result from milvus-text-search from milvus (local)
208+
209+
Here are the documents I found that mention machine learning:
210+
[Results will appear here based on your actual data]
211+
```
212+
213+
### **Using Cursor**
214+
215+
#### **Example: Creating a Collection**
216+
217+
In Cursor's Composer, you can ask:
218+
219+
```
220+
Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)
221+
```
222+
223+
Cursor will use the MCP server to execute this operation:
224+
225+
```
226+
I'll create a new collection called 'articles' with the specified fields.
227+
228+
> View result from milvus-create-collection from milvus (local)
229+
230+
Collection 'articles' has been created successfully with the following schema:
231+
- title: string
232+
- content: string
233+
- vector: float vector[128]
234+
```
235+
236+
## **Troubleshooting**
237+
238+
### **Common Issues**
239+
240+
#### **Connection Errors**
241+
242+
If you see errors like "Failed to connect to Milvus server":
243+
244+
1. Verify your Milvus instance is running: `docker ps` (if using Docker)
245+
2. Check the URI is correct in your configuration
246+
3. Ensure there are no firewall rules blocking the connection
247+
4. Try using `127.0.0.1` instead of `localhost` in the URI
248+
249+
#### **Authentication Issues**
250+
251+
If you see authentication errors:
252+
253+
1. Verify your `MILVUS_TOKEN` is correct
254+
2. Check if your Milvus instance requires authentication
255+
3. Ensure you have the correct permissions for the operations you're trying to perform
256+
257+
#### **Tool Not Found**
258+
259+
If the MCP tools don't appear in Claude Desktop or Cursor:
260+
261+
1. Restart the application
262+
2. Check the server logs for any errors
263+
3. Verify the MCP server is running correctly
264+
4. Press the refresh button in the MCP settings (for Cursor)
265+
266+
### **Getting Help**
267+
268+
If you continue to experience issues:
269+
270+
1. Check the [GitHub Issues](https://github.com/zilliztech/mcp-server-milvus/issues) for similar problems
271+
2. Join the [Zilliz Community Discord](https://discord.gg/zilliz) for support
272+
3. File a new issue with detailed information about your problem
273+
274+
## **Conclusion**
275+
By following this tutorial, you now have an **MCP server** running, enabling AI-powered vector search in Milvus. Whether you're using **Claude Desktop** or **Cursor**, you can now query, manage, and search your Milvus database using **natural language commands**—without writing database code!

0 commit comments

Comments
 (0)