Back to search
mcp-server-milvus
MCP serverGitHub
Model Context Protocol Servers for Milvus
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/zilliztech--mcp-server-milvus)HTML
<a href="/listings/zilliztech--mcp-server-milvus"><img src="/api/listings/zilliztech--mcp-server-milvus/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 500 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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](https://milvus.io/) vector database functionality.
- 
- ## Prerequisites
- Before using this MCP server, ensure you have:
- - Python 3.10 or higher
- - A running [Milvus](https://milvus.io/) instance (local or remote)
- - [uv](https://github.com/astral-sh/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:
- ```bash
- git clone https://github.com/zilliztech/mcp-server-milvus.git
- cd mcp-server-milvus
- ```
- Then you can run the server directly:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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:**
- ```bash
- 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:
- ```bash
- mcp dev src/mcp_server_milvus/server.py
- ```
- The output will be similar to:
- ```plaintext
- % 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.
- ### 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:**
- ```bash
- uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
- ```
- - `--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:**
- ```bash
- uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000
- ```
- ## 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:
- ```json
- {
- "mcpServers": {
- "milvus-sse": {
- "url": "http://your_sse_host:port/sse",
- "disabled": false,
- "autoApprove": []
- }
- }
- }
- ```
- #### Streamable HTTP Mode Configuration
- ```json
- {
- "mcpServers": {
- "milvus-streamable-http": {
- "url": "http://your_host:port/mcp",
- "disabled": false,
- "autoApprove": []
- }
- }
- }
- ```
- 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:
- ```json
- {
- "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 Claude Desktop to apply the changes.
- ## Usage with Cursor
- [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:
- ### 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:
- ```json
- {
- "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:
- ```bash
- 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:
- ```json
- {
- "mcpServers": {
- "milvus-sse": {
- "url": "http://your_sse_host:port/sse",
- "disabled": false,
- "autoApprove": []
- }
- }
- }
- ```
- #### For Streamable HTTP Mode:
- 1. Start the service:
- ```bash
- uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port
- ```
- 2. Update `mcp.json`:
- ```json
- {
- "mcpServers": {
- "milvus-streamable-http": {
- "url": "http://your_host:port/mcp",
- "disabled": false,
- "autoApprove": []
- }
- }
- }
- ```
- ### 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](https://milvus.io/docs/embedding-function-overview.md#Embedding-Function-Overview) 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 dictionary with the following keys:
- - `field_name`: name of the field to index
- - `index_type`: index type
- - `**kwargs`: other optional index parameters
- - `other_kwargs`: Additional keyword arguments for the collection creation
- - `milvus_load_collection`: Load a collection into memory for search and query
- - Parameters:
- - `collection_name`: Name of collection to load
- - `replica_number`: Number of replicas (default: 1)
- - `milvus_release_collection`: Release a collection from memory
- - Parameters:
- - `collection_name`: Name of collection to release
- - `milvus_get_collection_info`: Lists detailed information like schema, properties, collection ID, and other metadata of a specific collection.
- - Parameters:
- - `collection_name`: Name of the collection to get detailed information about
- ### Data Operations
- - `milvus_insert_data`: Insert data into a collection
- - Parameters:
- - `collection_name`: Name of collection
- - `data`: Dictionary mapping field names to lists of values
- - `milvus_delete_entities`: Delete entities from a collection based on filter expression
- - Parameters:
- - `collection_name`: Name of collection
- - `filter_expr`: Filter expression to select entities to delete
- ## Environment Variables
- - `MILVUS_URI`: Milvus server URI (can be set instead of --milvus-uri)
- - `MILVUS_TOKEN`: Optional authentication token
- - `MILVUS_DB`: Database name (defaults to "default")
- ## Development
- To run the server directly:
- ```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)
- 2. Check the URI is correct in your configuration
- 3. Ensure there are no firewall rules blocking the connection
- 4. 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
- 2. Check if your Milvus instance requires authentication
- 3. 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
- 2. Check the server logs for any errors
- 3. Verify 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](https://github.com/zilliztech/mcp-server-milvus/issues) for similar problems
- 2. Join the [Milvus Community Discord](https://milvus.io/discord) for support
- 3. File a new issue with detailed information about your problem
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.