Unleash the Power of LLMs with Milvus: Introducing the Model Context Protocol (MCP) Server

Seamlessly integrate Large Language Models (LLMs) with the robust vector search capabilities of Milvus using the Model Context Protocol (MCP). Build intelligent applications that leverage external data sources for enhanced context and accuracy.

This repository provides a production-ready MCP server designed to bridge the gap between LLMs and Milvus, the leading open-source vector database. Empower your AI-powered IDEs, intelligent chat interfaces, and custom AI workflows with the contextual awareness they need to excel.

Core Requirements

Before deploying this MCP server, ensure your environment meets the following prerequisites:

• Python: Version 3.10 or higher is mandatory.
• Milvus Instance: A fully operational Milvus instance, either local or remote, is required. Verify its accessibility.
• uv (Recommended): Leverage the speed and efficiency of uv for optimal server performance.

Deployment Strategies

The recommended deployment strategy involves running the MCP server directly with uv, eliminating the need for a separate installation step. This streamlined approach is the preferred configuration for both Claude Desktop and Cursor integrations, as demonstrated in the examples below.

For users who prefer a traditional approach, cloning the repository is also supported:

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

Direct Execution with uv

Execute the server directly using the following command, specifying the Milvus URI:

uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530

Environment Variable Configuration

Alternatively, configure the server using environment variables defined in the .env file located within the src/mcp_server_milvus/ directory. Then, execute the server with:

uv run src/mcp_server_milvus/server.py

Important Note: Environment variables defined in the .env file will override any command-line arguments. Prioritize your configuration strategy accordingly.

Compatible Applications

This MCP server is designed for seamless integration with a wide range of LLM applications that adhere to the Model Context Protocol:

• Claude Desktop: Anthropic's flagship desktop application for Claude.
• Cursor: The AI-powered code editor revolutionizing software development.
• Custom MCP Clients: Any application built upon the MCP client specification.

Integration Guides

Claude Desktop Integration

1. Installation: Download and install Claude Desktop from the official website: https://claude.ai/download

2. Configuration File: Access the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. MCP Server Configuration: Add the following JSON snippet to the claude_desktop_config.json file, adjusting the paths to reflect your local environment:

{
  "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: Restart Claude Desktop to apply the changes.

Cursor Integration

Cursor offers two methods for integrating the Milvus MCP server:

Option 1: Cursor Settings UI

1. Access Settings: Navigate to Cursor Settings > Features > MCP.

2. Add New Server: Click the "+ Add New MCP Server" button.

3. Configuration: Populate the form with the following details:

   • Type: Select stdio.
   • Name: milvus.
   • Command: /PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530

   ⚠️ Important: Use 127.0.0.1 instead of localhost to mitigate potential DNS resolution issues.

Option 2: Project-Specific Configuration (Recommended)

This approach provides a more isolated and manageable configuration.

1. Create Directory: Create the .cursor directory in your project root:

   mkdir -p /path/to/your/project/.cursor

2. Create Configuration File: Create a mcp.json file within the .cursor directory with the following content:

   {
     "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"
         ]
       }
     }
   }

3. Restart: Restart Cursor or reload the window to activate the configuration.

After adding the server, refresh the tool list in the MCP settings. Cursor will automatically leverage the Milvus tools when relevant to your queries.

Verification

Confirm successful integration by:

1. Navigating to Cursor Settings > Features > MCP.
2. Verifying that "Milvus" appears in the list of MCP servers.
3. Confirming that the available tools are listed (e.g., milvus_list_collections, milvus_vector_search).
4. Troubleshooting any errors displayed by the server.

Available Tools

This MCP server exposes a comprehensive suite of tools for interacting with Milvus:

Search and Query Operations

• milvus_text_search: Execute full-text searches within a specified collection.

  • Parameters:
    • collection_name: The name of the collection to search.
    • query_text: The text to search for.
    • limit: The maximum number of results to return (default: 5).
    • output_fields: A list of fields to include in the results.
    • drop_ratio: The proportion of low-frequency terms to ignore (0.0-1.0).

• milvus_vector_search: Perform vector similarity searches on a collection.

  • Parameters:
    • collection_name: The name of the collection to search.
    • vector: The query vector.
    • vector_field: The field containing the vectors to search (default: "vector").
    • limit: The maximum number of results to return (default: 5).
    • output_fields: A list of fields to include in the results.
    • metric_type: The distance metric to use (COSINE, L2, IP) (default: "COSINE").

• milvus_query: Query a collection using filter expressions.

  • Parameters:
    • collection_name: The name of the collection to query.
    • filter_expr: A filter expression (e.g., 'age > 20').
    • output_fields: A list of fields to include in the results.
    • limit: The maximum number of results to return (default: 10).

Collection Management

• milvus_list_collections: Retrieve a list of all collections in the database.

• milvus_create_collection: Create a new collection with a specified schema.

  • Parameters:
    • collection_name: The name for the new collection.
    • collection_schema: The collection schema definition.
    • index_params: Optional index parameters.

• milvus_load_collection: Load a collection into memory for search and query operations.

  • Parameters:
    • collection_name: The name of the collection to load.
    • replica_number: The number of replicas (default: 1).

• milvus_release_collection: Release a collection from memory.

  • Parameters:
    • collection_name: The name of the collection to release.

Data Operations

• milvus_insert_data: Insert data into a collection.

  • Parameters:
    • collection_name: The name of the collection.
    • data: A dictionary mapping field names to lists of values.

• milvus_delete_entities: Delete entities from a collection based on a filter expression.

  • Parameters:
    • collection_name: The name of the collection.
    • filter_expr: A filter expression to select entities to delete.

Environment Variables

Configure the server using the following environment variables:

• MILVUS_URI: The Milvus server URI (alternative to the --milvus-uri command-line argument).
• MILVUS_TOKEN: An optional authentication token.
• MILVUS_DB: The database name (defaults to "default").

Development

For local development, run the server directly:

uv run server.py --milvus-uri http://localhost:19530

Example Use Cases

Claude Desktop

Listing Collections

What are the collections I have in my Milvus DB?

Claude will use MCP to retrieve this information from your Milvus database.

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

Searching for Documents

Find documents in my text_collection that mention "machine learning"

Claude will leverage Milvus's full-text search capabilities 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]

Cursor

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 encounter errors such as "Failed to connect to Milvus server":

1. Verify that your Milvus instance is running (e.g., using docker ps if using Docker).
2. Double-check the URI in your configuration.
3. Ensure that no firewall rules are blocking the connection.
4. Try using 127.0.0.1 instead of localhost in the URI.

Authentication Issues

If you encounter authentication errors:

1. Verify that your MILVUS_TOKEN is correct.
2. Check if your Milvus instance requires authentication.
3. Ensure that you have the correct permissions for the operations you are trying to perform.

Tool Not Found

If the MCP tools do not appear in Claude Desktop or Cursor:

1. Restart the application.
2. Check the server logs for any errors.
3. Verify that 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 for similar problems.
2. Join the Zilliz Community Discord for support.
3. File a new issue with detailed information about your problem.