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 vector database functionality.

Prerequisites

Before using this MCP server, ensure you have:

• Python 3.10 or higher
• A running Milvus instance (local or remote)
• 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:

git clone https://github.com/zilliztech/mcp-server-milvus.git
cd mcp-server-milvus

Then you can run the server directly:

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:

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:

  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:

  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:

  mcp dev src/mcp_server_milvus/server.py
  

  The output will be similar to:

  % 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:

*Configuration content*

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:

*Configuration content*

4. Restart Claude Desktop to apply the changes.

Usage with Cursor

Cursor also supports MCP 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:

*Configuration content*

For SSE Mode:

1. Start the service by running the following command:

   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:

   *Configuration content*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)
1. Check the URI is correct in your configuration
1. Ensure there are no firewall rules blocking the connection
1. 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
1. Check if your Milvus instance requires authentication
1. 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
1. Check the server logs for any errors
1. Verify the MCP server is running correctly
1. 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
1. Join the [Zilliz Community Discord](https://discord.gg/zilliz) for support
1. File a new issue with detailed information about your problem