{"id":26648386,"url":"https://github.com/zilliztech/mcp-server-milvus","last_synced_at":"2025-10-08T00:11:43.514Z","repository":{"id":283168186,"uuid":"943619628","full_name":"zilliztech/mcp-server-milvus","owner":"zilliztech","description":"Model Context Protocol Servers for Milvus","archived":false,"fork":false,"pushed_at":"2025-06-05T12:59:48.000Z","size":7389,"stargazers_count":168,"open_issues_count":14,"forks_count":45,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-19T21:54:06.356Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zilliztech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-06T02:10:40.000Z","updated_at":"2025-08-19T10:40:14.000Z","dependencies_parsed_at":"2025-04-25T09:23:17.975Z","dependency_job_id":"d66b7c5d-a9d1-46ce-9ff0-04abc72de3cc","html_url":"https://github.com/zilliztech/mcp-server-milvus","commit_stats":null,"previous_names":["zilliztech/mcp-server-milvus"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zilliztech/mcp-server-milvus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Fmcp-server-milvus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Fmcp-server-milvus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Fmcp-server-milvus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Fmcp-server-milvus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zilliztech","download_url":"https://codeload.github.com/zilliztech/mcp-server-milvus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zilliztech%2Fmcp-server-milvus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278867210,"owners_count":26059738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-25T00:01:53.208Z","updated_at":"2025-10-08T00:11:43.508Z","avatar_url":"https://github.com/zilliztech.png","language":"Python","funding_links":[],"categories":["🏢 Enterprise-Supported Implementations","Databases","Database \u0026 Messaging MCP Servers","Wissen und Gedächtnis","📚 Projects (1974 total)","Production-Ready Servers","🤖 AI/ML","پیاده‌سازی‌های سرور","Task and Project Management","Official Servers","MCP 服务器精选列表","官方 MCP 服务器列表","Python","Databases and Data","Table of Contents","🗂️ Extensions by Category","Data \u0026 Analytics","🗄️ Databases (68 servers)","Server Implementations","Agent Communication Protocols"],"sub_categories":["Databases \u0026 Storage","Vector Databases","Claude API","Dieselbe Konfiguration, CLI und IDE","MCP Servers","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eپایگاه‌های داده","🗄️ 数据库交互","How to Submit","Databases","🗄️ Databases","🗄️ \u003ca name=\"databases\"\u003e\u003c/a\u003eDatabases","Model Context Protocol (MCP)"],"readme":"# MCP Server for Milvus\n\n\u003e 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## 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\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` \u003e `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   \u003e **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### 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` \u003e `MCP`\n2. Check if \"milvus\" or \"milvus-sse\" 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)\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- `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\n    - `output_fields`: Fields to include in results\n    - `filter_expr`: Filter expression\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 \u003e 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 specified schema\n\n  - Parameters:\n    - `collection_name`: Name for the new collection\n    - `collection_schema`: Collection schema definition\n    - `index_params`: Optional index parameters\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\u003e 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 [Zilliz Community Discord](https://discord.gg/zilliz) for support\n3. File a new issue with detailed information about your problem\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilliztech%2Fmcp-server-milvus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzilliztech%2Fmcp-server-milvus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzilliztech%2Fmcp-server-milvus/lists"}