README.md•12.4 kB
# MCP Server for Milvus
> 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.
This repository contains a MCP server that provides access to [Milvus](https://milvus.io/) vector database functionality.
## Prerequisites
Before using this MCP server, ensure you have:
- Python 3.10 or higher
- A running [Milvus](https://milvus.io/) instance (local or remote)
- [uv](https://github.com/astral-sh/uv) installed (recommended for running the server)
## Usage
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.
If you want to clone the repository:
```bash
git clone https://github.com/zilliztech/mcp-server-milvus.git
cd mcp-server-milvus
```
Then you can run the server directly:
```bash
uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530
```
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:
```bash
uv run src/mcp_server_milvus/server.py
```
### Important: the .env file will have higher priority than the command line arguments.
### Running Modes
The server supports two running modes: **stdio** (default) and **SSE** (Server-Sent Events).
### Stdio Mode (Default)
- **Description**: Communicates with the client via standard input/output. This is the default mode if no mode is specified.
- Usage:
```bash
uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530
```
### SSE Mode
- **Description**: Uses HTTP Server-Sent Events for communication. This mode allows multiple clients to connect via HTTP and is suitable for web-based applications.
- **Usage:**
```bash
uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
```
- `--sse`: Enables SSE mode.
- `--port`: Specifies the port for the SSE server (default: 8000).
- **Debugging in SSE Mode:**
If you want to debug in SSE mode, after starting the SSE service, enter the following command:
```bash
mcp dev src/mcp_server_milvus/server.py
```
The output will be similar to:
```plaintext
% mcp dev src/mcp_server_milvus/merged_server.py
Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
```
You can then access the MCP Inspector at `http://127.0.0.1:6274` for testing.
## Supported Applications
This MCP server can be used with various LLM applications that support the Model Context Protocol:
- **Claude Desktop**: Anthropic's desktop application for Claude
- **Cursor**: AI-powered code editor with MCP support
- **Custom MCP clients**: Any application implementing the MCP client specification
## Usage with Claude Desktop
### Configuration for Different Modes
#### SSE Mode Configuration
Follow these steps to configure Claude Desktop for SSE mode:
1. Install Claude Desktop from https://claude.ai/download.
2. Open your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
3. Add the following configuration for SSE mode:
```json
{
"mcpServers": {
"milvus-sse": {
"url": "http://your_sse_host:port/sse",
"disabled": false,
"autoApprove": []
}
}
}
```
4. Restart Claude Desktop to apply the changes.
#### Stdio Mode Configuration
For stdio mode, follow these steps:
1. Install Claude Desktop from https://claude.ai/download.
2. Open your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
3. Add the following configuration for stdio mode:
```json
{
"mcpServers": {
"milvus": {
"command": "/PATH/TO/uv",
"args": [
"--directory",
"/path/to/mcp-server-milvus/src/mcp_server_milvus",
"run",
"server.py",
"--milvus-uri",
"http://localhost:19530"
]
}
}
}
```
4. Restart Claude Desktop to apply the changes.
## Usage with Cursor
[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:
### Integration Steps
1. Open `Cursor Settings` > `MCP`
2. Click on `Add new global MCP server`
3. After clicking, it will automatically redirect you to the `mcp.json` file, which will be created if it doesn’t exist
### Configuring the `mcp.json` File
#### For Stdio Mode:
Overwrite the `mcp.json` file with the following content:
```json
{
"mcpServers": {
"milvus": {
"command": "/PATH/TO/uv",
"args": [
"--directory",
"/path/to/mcp-server-milvus/src/mcp_server_milvus",
"run",
"server.py",
"--milvus-uri",
"http://127.0.0.1:19530"
]
}
}
}
```
#### For SSE Mode:
1. Start the service by running the following command:
```bash
uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
```
> **Note**: Replace `http://your_sse_host` with your actual SSE host address and `port` with the specific port number you’re using.
2. Once the service is up and running, overwrite the `mcp.json` file with the following content:
```json
{
"mcpServers": {
"milvus-sse": {
"url": "http://your_sse_host:port/sse",
"disabled": false,
"autoApprove": []
}
}
}
```
### Completing the Integration
After completing the above steps, restart Cursor or reload the window to ensure the configuration takes effect.
## Verifying the Integration
To verify that Cursor has successfully integrated with your Milvus MCP server:
1. Open `Cursor Settings` > `MCP`
2. Check if "milvus" or "milvus-sse" appear in the list（depending on the mode you have chosen）
3. Confirm that the relevant tools are listed (e.g., milvus_list_collections, milvus_vector_search, etc.)
4. If the server is enabled but shows an error, check the Troubleshooting section below
## Available Tools
The server provides the following tools:
### Search and Query Operations
- `milvus_text_search`: Search for documents using full text search
- Parameters:
- `collection_name`: Name of collection to search
- `query_text`: Text to search for
- `limit`: The maximum number of results to return (default: 5)
- `output_fields`: Fields to include in results
- `drop_ratio`: Proportion of low-frequency terms to ignore (0.0-1.0)
- `milvus_vector_search`: Perform vector similarity search on a collection
- Parameters:
- `collection_name`: Name of collection to search
- `vector`: Query vector
- `vector_field`: Field name for vector search (default: "vector")
- `limit`: The maximum number of results to return (default: 5)
- `output_fields`: Fields to include in results
- `filter_expr`: Filter expression
- `metric_type`: Distance metric (COSINE, L2, IP) (default: "COSINE")
- `milvus_hybrid_search`: Perform hybrid search on a collection
- Parameters:
- `collection_name`: Name of collection to search
- `query_text`: Text query for search
- `text_field`: Field name for text search
- `vector`: Vector of the text query
- `vector_field`: Field name for vector search
- `limit`: The maximum number of results to return
- `output_fields`: Fields to include in results
- `filter_expr`: Filter expression
- `milvus_query`: Query collection using filter expressions
- Parameters:
- `collection_name`: Name of collection to query
- `filter_expr`: Filter expression (e.g. 'age > 20')
- `output_fields`: Fields to include in results
- `limit`: The maximum number of results to return (default: 10)
### Collection Management
- `milvus_list_collections`: List all collections in the database
- `milvus_create_collection`: Create a new collection with specified schema
- Parameters:
- `collection_name`: Name for the new collection
- `collection_schema`: Collection schema definition
- `index_params`: Optional index parameters
- `milvus_load_collection`: Load a collection into memory for search and query
- Parameters:
- `collection_name`: Name of collection to load
- `replica_number`: Number of replicas (default: 1)
- `milvus_release_collection`: Release a collection from memory
- Parameters:
- `collection_name`: Name of collection to release
- `milvus_get_collection_info`: Lists detailed information like schema, properties, collection ID, and other metadata of a specific collection.
- Parameters:
- `collection_name`: Name of the collection to get detailed information about
### Data Operations
- `milvus_insert_data`: Insert data into a collection
- Parameters:
- `collection_name`: Name of collection
- `data`: Dictionary mapping field names to lists of values
- `milvus_delete_entities`: Delete entities from a collection based on filter expression
- Parameters:
- `collection_name`: Name of collection
- `filter_expr`: Filter expression to select entities to delete
## Environment Variables
- `MILVUS_URI`: Milvus server URI (can be set instead of --milvus-uri)
- `MILVUS_TOKEN`: Optional authentication token
- `MILVUS_DB`: Database name (defaults to "default")
## Development
To run the server directly:
```bash
uv run server.py --milvus-uri http://localhost:19530
```
## Examples
### Using Claude Desktop
#### Example 1: Listing Collections
```
What are the collections I have in my Milvus DB?
```
Claude will then use MCP to check this information on your Milvus DB.
```
I'll check what collections are available in your Milvus database.
Here are the collections in your Milvus database:
1. rag_demo
2. test
3. chat_messages
4. text_collection
5. image_collection
6. customized_setup
7. streaming_rag_demo
```
#### Example 2: Searching for Documents
```
Find documents in my text_collection that mention "machine learning"
```
Claude will use the full-text search capabilities of Milvus to find relevant documents:
```
I'll search for documents about machine learning in your text_collection.
> View result from milvus-text-search from milvus (local)
Here are the documents I found that mention machine learning:
[Results will appear here based on your actual data]
```
### Using Cursor
#### Example: Creating a Collection
In Cursor, you can ask:
```
Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)
```
Cursor will use the MCP server to execute this operation:
```
I'll create a new collection called 'articles' with the specified fields.
Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float vector[128]
```
## Troubleshooting
### Common Issues
#### Connection Errors
If you see errors like "Failed to connect to Milvus server":
1. Verify your Milvus instance is running: `docker ps` (if using Docker)
2. Check the URI is correct in your configuration
3. Ensure there are no firewall rules blocking the connection
4. Try using `127.0.0.1` instead of `localhost` in the URI
#### Authentication Issues
If you see authentication errors:
1. Verify your `MILVUS_TOKEN` is correct
2. Check if your Milvus instance requires authentication
3. Ensure you have the correct permissions for the operations you're trying to perform
#### Tool Not Found
If the MCP tools don't appear in Claude Desktop or Cursor:
1. Restart the application
2. Check the server logs for any errors
3. Verify the MCP server is running correctly
4. Press the refresh button in the MCP settings (for Cursor)
### Getting Help
If you continue to experience issues:
1. Check the [GitHub Issues](https://github.com/zilliztech/mcp-server-milvus/issues) for similar problems
2. Join the [Zilliz Community Discord](https://discord.gg/zilliz) for support
3. File a new issue with detailed information about your problem
