Server Milvus

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

  Copy to clipboard

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

  Copy to clipboard
  • --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

  Copy to clipboard

  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 🚀

  Copy to clipboard

  You can then access the MCP Inspector at http://127.0.0.1:6274 for testing.

Streamable HTTP Mode

• Description: Uses HTTP with streaming support for communication. This is the recommended transport for production deployments and supports both stateful and stateless operation.

• Usage:

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

  Copy to clipboard
  • --streamable-http: Enables Streamable HTTP mode.
  • --port: Specifies the port for the server (default: 8000).
  • --stateless: Optional flag for stateless mode (no session persistence).

• Stateless Mode:

  uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000

  Copy to clipboard

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:

{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Streamable HTTP Mode Configuration

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

1. 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:

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

1. 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:

{
  "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:

   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port

   Copy to clipboard

   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:

   {
       "mcpServers": {
         "milvus-sse": {
           "url": "http://your_sse_host:port/sse",
           "disabled": false,
           "autoApprove": []
         }
       }
   }

   Copy to clipboard

For Streamable HTTP Mode:

1. Start the service:

   uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port

   Copy to clipboard

2. Update mcp.json:

   {
     "mcpServers": {
       "milvus-streamable-http": {
         "url": "http://your_host:port/mcp",
         "disabled": false,
         "autoApprove": []
       }
     }
   }

   Copy to clipboard

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", "milvus-sse", or "milvus-streamable-http" 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) (default: 0.2)

• 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")
    • radius: Optional lower bound for range search (default: None)
    • range_filter: Optional upper bound for range search (default: None)

• 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 (default: 5)
    • output_fields: Fields to include in results
    • filter_expr: Filter expression
    • sparse_radius: Optional lower bound for sparse range search (default: None)
    • sparse_range_filter: Optional upper bound for sparse range search (default: None)
    • dense_radius: Optional lower bound for dense range search (default: None)
    • dense_range_filter: Optional upper bound for dense range search (default: None)

• milvus_text_similarity_search: Perform text similarity search on a collection

  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 for more details.

  • Parameters:
    • collection_name: Name of collection to search
    • query_text: Text query for similarity search
    • anns_field: Field name for text search
    • limit: The maximum number of results to return (default: 5)
    • output_fields: Fields to include in results
    • metric_type: Distance metric (COSINE, L2, IP) (default: "COSINE")
    • filter_expr: Optional filter expression
    • radius: Optional lower bound for range search (default: None)
    • range_filter: Optional upper bound for range search (default: None)

• 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 quick setup or customized schema

  • Parameters:
    • collection_name: Name for the new collection
    • auto_id: whether to auto generate id, default to True
    • dimension: vector dimension, default to 768; for quick setup and will be ignored if field_schema is provided
    • primary_field_name: name of the primary field, default to "id"; for quick setup and will be ignored if field_schema is provided
    • vector_field_name: name of the vector field, default to "vector"; for quick setup and will be ignored if field_schema is provided
    • metric_type: metric type, default to "COSINE"; for quick setup and will be ignored if field_schema is provided
    • field_schema: List of field schema, each element is a dictionary with the following keys:
      • name: name of the field
      • type: type of the field
    • index_params: Optional list of index parameters, each element is a dict

…