{
  "markdown": "# MCP Server for Milvus\n\n> 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.\n\nThis repository contains a MCP server that provides access to [Milvus](https://milvus.io/) vector database functionality.\n\n![MCP with Milvus](Claude_mcp+1080.gif)\n\n## Prerequisites\n\nBefore using this MCP server, ensure you have:\n\n- Python 3.10 or higher\n- A running [Milvus](https://milvus.io/) instance (local or remote)\n- [uv](https://github.com/astral-sh/uv) installed (recommended for running the server)\n\n## Usage\n\nThe 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.\n\nIf you want to clone the repository:\n\n```bash\ngit clone https://github.com/zilliztech/mcp-server-milvus.git\ncd mcp-server-milvus\n```\n\nThen you can run the server directly:\n\n```bash\nuv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530\n```\n\nAlternatively 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:\n\n```bash\nuv run src/mcp_server_milvus/server.py\n```\n\n### Important: the .env file will have higher priority than the command line arguments.\n\n### Running Modes\n\nThe server supports two running modes: **stdio** (default) and **SSE** (Server-Sent Events).\n\n### Stdio Mode (Default)\n\n- **Description**: Communicates with the client via standard input/output. This is the default mode if no mode is specified.\n\n- Usage:\n\n  ```bash\n  uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530\n  ```\n\n### SSE Mode\n\n- **Description**: Uses HTTP Server-Sent Events for communication. This mode allows multiple clients to connect via HTTP and is suitable for web-based applications.\n\n- **Usage:**\n\n  ```bash\n  uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000\n  ```\n\n  - `--sse`: Enables SSE mode.\n  - `--port`: Specifies the port for the SSE server (default: 8000).\n\n- **Debugging in SSE Mode:**\n\n  If you want to debug in SSE mode, after starting the SSE service, enter the following command:\n\n  ```bash\n  mcp dev src/mcp_server_milvus/server.py\n  ```\n\n  The output will be similar to:\n\n  ```plaintext\n  % mcp dev src/mcp_server_milvus/merged_server.py\n  Starting MCP inspector...\n  ⚙️ Proxy server listening on port 6277\n  🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀\n  ```\n\n  You can then access the MCP Inspector at `http://127.0.0.1:6274` for testing.\n\n### Streamable HTTP Mode\n\n- **Description**: Uses HTTP with streaming support for communication. This is the recommended transport for production deployments and supports both stateful and stateless operation.\n\n- **Usage:**\n\n  ```bash\n  uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000\n  ```\n\n  - `--streamable-http`: Enables Streamable HTTP mode.\n  - `--port`: Specifies the port for the server (default: 8000).\n  - `--stateless`: Optional flag for stateless mode (no session persistence).\n\n- **Stateless Mode:**\n\n  ```bash\n  uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000\n  ```\n\n## Supported Applications\n\nThis MCP server can be used with various LLM applications that support the Model Context Protocol:\n\n- **Claude Desktop**: Anthropic's desktop application for Claude\n- **Cursor**: AI-powered code editor with MCP support\n- **Custom MCP clients**: Any application implementing the MCP client specification\n\n## Usage with Claude Desktop\n\n### Configuration for Different Modes\n\n#### SSE Mode Configuration\n\nFollow these steps to configure Claude Desktop for SSE mode:\n\n1. Install Claude Desktop from https://claude.ai/download.\n2. Open your Claude Desktop configuration file:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n3. Add the following configuration for SSE mode:\n\n```json\n{\n  \"mcpServers\": {\n    \"milvus-sse\": {\n      \"url\": \"http://your_sse_host:port/sse\",\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n#### Streamable HTTP Mode Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"milvus-streamable-http\": {\n      \"url\": \"http://your_host:port/mcp\",\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n\n4. Restart Claude Desktop to apply the changes.\n\n#### Stdio Mode Configuration\n\nFor stdio mode, follow these steps:\n\n1. Install Claude Desktop from https://claude.ai/download.\n2. Open your Claude Desktop configuration file:\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n3. Add the following configuration for stdio mode:\n\n```json\n{\n  \"mcpServers\": {\n    \"milvus\": {\n      \"command\": \"/PATH/TO/uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/mcp-server-milvus/src/mcp_server_milvus\",\n        \"run\",\n        \"server.py\",\n        \"--milvus-uri\",\n        \"http://localhost:19530\"\n      ]\n    }\n  }\n}\n```\n\n4. Restart Claude Desktop to apply the changes.\n\n## Usage with Cursor\n\n[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:\n\n### Integration Steps\n\n1. Open `Cursor Settings` > `MCP`\n2. Click on `Add new global MCP server`\n3. After clicking, it will automatically redirect you to the `mcp.json` file, which will be created if it doesn’t exist\n\n### Configuring the `mcp.json` File\n\n#### For Stdio Mode:\n\nOverwrite the `mcp.json` file with the following content:\n\n```json\n{\n  \"mcpServers\": {\n    \"milvus\": {\n      \"command\": \"/PATH/TO/uv\",\n      \"args\": [\n        \"--directory\",\n        \"/path/to/mcp-server-milvus/src/mcp_server_milvus\",\n        \"run\",\n        \"server.py\",\n        \"--milvus-uri\",\n        \"http://127.0.0.1:19530\"\n      ]\n    }\n  }\n}\n```\n\n#### For SSE Mode:\n\n1. Start the service by running the following command:\n\n   ```bash\n   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port\n   ```\n\n   > **Note**: Replace `http://your_sse_host` with your actual SSE host address and `port` with the specific port number you’re using.\n\n2. Once the service is up and running, overwrite the `mcp.json` file with the following content:\n\n   ```json\n   {\n       \"mcpServers\": {\n         \"milvus-sse\": {\n           \"url\": \"http://your_sse_host:port/sse\",\n           \"disabled\": false,\n           \"autoApprove\": []\n         }\n       }\n   }\n   ```\n\n#### For Streamable HTTP Mode:\n\n1. Start the service:\n\n   ```bash\n   uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port\n   ```\n\n2. Update `mcp.json`:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"milvus-streamable-http\": {\n         \"url\": \"http://your_host:port/mcp\",\n         \"disabled\": false,\n         \"autoApprove\": []\n       }\n     }\n   }\n   ```\n\n### Completing the Integration\n\nAfter completing the above steps, restart Cursor or reload the window to ensure the configuration takes effect.\n\n## Verifying the Integration\n\nTo verify that Cursor has successfully integrated with your Milvus MCP server:\n\n1. Open `Cursor Settings` > `MCP`\n2. Check if \"milvus\", \"milvus-sse\", or \"milvus-streamable-http\" appear in the list (depending on the mode you have chosen)\n3. Confirm that the relevant tools are listed (e.g., milvus_list_collections, milvus_vector_search, etc.)\n4. If the server is enabled but shows an error, check the Troubleshooting section below\n\n## Available Tools\n\nThe server provides the following tools:\n\n### Search and Query Operations\n\n- `milvus_text_search`: Search for documents using full text search\n\n  - Parameters:\n    - `collection_name`: Name of collection to search\n    - `query_text`: Text to search for\n    - `limit`: The maximum number of results to return (default: 5)\n    - `output_fields`: Fields to include in results\n    - `drop_ratio`: Proportion of low-frequency terms to ignore (0.0-1.0) (default: 0.2)\n- `milvus_vector_search`: Perform vector similarity search on a collection\n  - Parameters:\n    - `collection_name`: Name of collection to search\n    - `vector`: Query vector\n    - `vector_field`: Field name for vector search (default: \"vector\")\n    - `limit`: The maximum number of results to return (default: 5)\n    - `output_fields`: Fields to include in results\n    - `filter_expr`: Filter expression\n    - `metric_type`: Distance metric (COSINE, L2, IP) (default: \"COSINE\")\n    - `radius`: Optional lower bound for range search (default: None)\n    - `range_filter`: Optional upper bound for range search (default: None)\n- `milvus_hybrid_search`: Perform hybrid search on a collection\n  - Parameters:\n    - `collection_name`: Name of collection to search\n    - `query_text`: Text query for search\n    - `text_field`: Field name for text search\n    - `vector`: Vector of the text query\n    - `vector_field`: Field name for vector search\n    - `limit`: The maximum number of results to return (default: 5)\n    - `output_fields`: Fields to include in results\n    - `filter_expr`: Filter expression\n    - `sparse_radius`: Optional lower bound for sparse range search (default: None)\n    - `sparse_range_filter`: Optional upper bound for sparse range search (default: None)\n    - `dense_radius`: Optional lower bound for dense range search (default: None)\n    - `dense_range_filter`: Optional upper bound for dense range search (default: None)\n- `milvus_text_similarity_search`: Perform text similarity search on a collection\n  > **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](https://milvus.io/docs/embedding-function-overview.md#Embedding-Function-Overview) for more details.\n  - Parameters:\n    - `collection_name`: Name of collection to search\n    - `query_text`: Text query for similarity search\n    - `anns_field`: Field name for text search\n    - `limit`: The maximum number of results to return (default: 5)\n    - `output_fields`: Fields to include in results\n    - `metric_type`: Distance metric (COSINE, L2, IP) (default: \"COSINE\")\n    - `filter_expr`: Optional filter expression\n    - `radius`: Optional lower bound for range search (default: None)\n    - `range_filter`: Optional upper bound for range search (default: None)\n- `milvus_query`: Query collection using filter expressions\n  - Parameters:\n    - `collection_name`: Name of collection to query\n    - `filter_expr`: Filter expression (e.g. 'age > 20')\n    - `output_fields`: Fields to include in results\n    - `limit`: The maximum number of results to return (default: 10)\n\n### Collection Management\n\n- `milvus_list_collections`: List all collections in the database\n\n- `milvus_create_collection`: Create a new collection with quick setup or customized schema\n\n  - Parameters:\n    - `collection_name`: Name for the new collection\n    - `auto_id`: whether to auto generate id, default to True\n    - `dimension`: vector dimension, default to 768; for quick setup and will be ignored if `field_schema` is provided\n    - `primary_field_name`: name of the primary field, default to \"id\"; for quick setup and will be ignored if `field_schema` is provided\n    - `vector_field_name`: name of the vector field, default to \"vector\"; for quick setup and will be ignored if `field_schema` is provided\n    - `metric_type`: metric type, default to \"COSINE\"; for quick setup and will be ignored if `field_schema` is provided\n    - `field_schema`: List of field schema, each element is a dictionary with the following keys:\n        - `name`: name of the field\n        - `type`: type of the field\n    - `index_params`: Optional list of index parameters, each element is a dictionary with the following keys:\n        - `field_name`: name of the field to index\n        - `index_type`: index type\n        - `**kwargs`: other optional index parameters\n    - `other_kwargs`: Additional keyword arguments for the collection creation\n\n- `milvus_load_collection`: Load a collection into memory for search and query\n\n  - Parameters:\n    - `collection_name`: Name of collection to load\n    - `replica_number`: Number of replicas (default: 1)\n\n- `milvus_release_collection`: Release a collection from memory\n  - Parameters:\n    - `collection_name`: Name of collection to release\n\n- `milvus_get_collection_info`: Lists detailed information like schema, properties, collection ID, and other metadata of a specific collection.\n  - Parameters:\n    - `collection_name`:  Name of the collection to get detailed information about\n\n### Data Operations\n\n- `milvus_insert_data`: Insert data into a collection\n\n  - Parameters:\n    - `collection_name`: Name of collection\n    - `data`: Dictionary mapping field names to lists of values\n\n- `milvus_delete_entities`: Delete entities from a collection based on filter expression\n  - Parameters:\n    - `collection_name`: Name of collection\n    - `filter_expr`: Filter expression to select entities to delete\n\n## Environment Variables\n\n- `MILVUS_URI`: Milvus server URI (can be set instead of --milvus-uri)\n- `MILVUS_TOKEN`: Optional authentication token\n- `MILVUS_DB`: Database name (defaults to \"default\")\n\n## Development\n\nTo run the server directly:\n\n```bash\nuv run server.py --milvus-uri http://localhost:19530\n```\n\n## Examples\n\n### Using Claude Desktop\n\n#### Example 1: Listing Collections\n\n```\nWhat are the collections I have in my Milvus DB?\n```\n\nClaude will then use MCP to check this information on your Milvus DB.\n\n```\nI'll check what collections are available in your Milvus database.\n\nHere are the collections in your Milvus database:\n\n1. rag_demo\n2. test\n3. chat_messages\n4. text_collection\n5. image_collection\n6. customized_setup\n7. streaming_rag_demo\n```\n\n#### Example 2: Searching for Documents\n\n```\nFind documents in my text_collection that mention \"machine learning\"\n```\n\nClaude will use the full-text search capabilities of Milvus to find relevant documents:\n\n```\nI'll search for documents about machine learning in your text_collection.\n\n> View result from milvus-text-search from milvus (local)\n\nHere are the documents I found that mention machine learning:\n[Results will appear here based on your actual data]\n```\n\n### Using Cursor\n\n#### Example: Creating a Collection\n\nIn Cursor, you can ask:\n\n```\nCreate a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)\n```\n\nCursor will use the MCP server to execute this operation:\n\n```\nI'll create a new collection called 'articles' with the specified fields.\n\nCollection 'articles' has been created successfully with the following schema:\n- title: string\n- content: string\n- vector: float vector[128]\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Connection Errors\n\nIf you see errors like \"Failed to connect to Milvus server\":\n\n1. Verify your Milvus instance is running: `docker ps` (if using Docker)\n2. Check the URI is correct in your configuration\n3. Ensure there are no firewall rules blocking the connection\n4. Try using `127.0.0.1` instead of `localhost` in the URI\n\n#### Authentication Issues\n\nIf you see authentication errors:\n\n1. Verify your `MILVUS_TOKEN` is correct\n2. Check if your Milvus instance requires authentication\n3. Ensure you have the correct permissions for the operations you're trying to perform\n\n#### Tool Not Found\n\nIf the MCP tools don't appear in Claude Desktop or Cursor:\n\n1. Restart the application\n2. Check the server logs for any errors\n3. Verify the MCP server is running correctly\n4. Press the refresh button in the MCP settings (for Cursor)\n\n### Getting Help\n\nIf you continue to experience issues:\n\n1. Check the [GitHub Issues](https://github.com/zilliztech/mcp-server-milvus/issues) for similar problems\n2. Join the [Milvus Community Discord](https://milvus.io/discord) for support\n3. File a new issue with detailed information about your problem\n",
  "bytes": 16175,
  "sha": "d7a073a9e162218fd866434567194cef3114288fa6ea07a0fb899de5ff4da062",
  "repo_slug": "zilliztech/mcp-server-milvus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_zilliztech_mcp_server_milvus_8a10a866/readme"
}