📌Overview

Purpose: The Model Context Protocol (MCP) framework aims to facilitate seamless integration between large language model (LLM) applications and external data sources, enabling enhanced functionality and custom workflows.

Overview: The MCP server for Milvus provides a robust interface to connect LLM applications with the Milvus vector database, offering various operations for data retrieval and management. It acts as a middleware, standardizing communication and ensuring that LLMs can access necessary contextual information efficiently.

Key Features:

MCP Standardization: Offers a unified protocol for LLM applications to interact with external data sources, enhancing compatibility and flexibility across different tools.
Rich Tool Set: Includes functionalities for text search, vector similarity search, collection management, and data operations, such as creating, loading, and deleting collections and entities.
Support for Multiple LLM Applications: Compatible with applications like Claude Desktop and Cursor, allowing easy integration and utilization of Milvus capabilities within popular AI tools.

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 an MCP server that provides access to the 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.

If you want to clone the repository:

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

Then run the server directly:

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

Alternatively, modify the .env file in the src/mcp_server_milvus/ directory to set environment variables and run the server with:

uv run src/mcp_server_milvus/server.py

Important: The .env file has higher priority than command line arguments.

Supported Applications

This MCP server can be used with various LLM applications that support MCP, including:

Claude Desktop: Anthropic's desktop application for Claude
Cursor: AI-powered code editor with MCP support
Custom MCP clients implementing the MCP client specification

Usage with Claude Desktop

Install Claude Desktop from https://claude.ai/download
Open your Claude Desktop configuration:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Add the following configuration:

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

Restart Claude Desktop.

Usage with Cursor

Cursor supports MCP tools. Add the Milvus MCP server to Cursor in two ways:

Option 1: Using Cursor Settings UI

Go to Cursor Settings > Features > MCP
Click on + Add New MCP Server
Fill out the form:
- 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

⚠️ Use 127.0.0.1 instead of localhost to avoid potential DNS resolution issues.

Option 2: Using Project-specific Configuration (Recommended)

Create a .cursor/mcp.json file in your project root.

Create .cursor directory:
```
mkdir -p /path/to/your/project/.cursor
```
Create mcp.json with:

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

Restart Cursor or reload the window.

After adding the server, press refresh in the MCP settings to populate the tool list. The Agent will automatically use Milvus tools when relevant.

Verifying the Integration

Open Cursor Settings > Features > MCP
Check that "Milvus" appears in the list
Verify the tools are listed (e.g., milvus_list_collections, milvus_vector_search)
If errors appear, see Troubleshooting section

Available Tools

Search and Query Operations

milvus_text_search: Search documents using full text search
- Parameters:
  - collection_name: Collection to search
  - query_text: Query string
  - limit: Max results (default: 5)
  - output_fields: Fields to include in results
  - drop_ratio: Proportion of low-frequency terms to ignore (0.0-1.0)
milvus_vector_search: Vector similarity search
- Parameters:
  - collection_name
  - vector: Query vector
  - vector_field: Vector field name (default: "vector")
  - limit: Max results (default: 5)
  - output_fields
  - metric_type: Distance metric (COSINE, L2, IP) (default: "COSINE")
milvus_query: Query using filter expressions
- Parameters:
  - collection_name
  - filter_expr: e.g., 'age > 20'
  - output_fields
  - limit: Max results (default: 10)

Collection Management

milvus_list_collections: List all collections
milvus_create_collection: Create a collection
- Parameters:
  - collection_name
  - collection_schema
  - index_params (optional)
milvus_load_collection: Load collection into memory
- Parameters:
  - collection_name
  - replica_number (default: 1)
milvus_release_collection: Release collection from memory
- Parameters:
  - collection_name

Data Operations

milvus_insert_data: Insert data
- Parameters:
  - collection_name
  - data: Field names to lists of values
milvus_delete_entities: Delete entities based on filter
- Parameters:
  - collection_name
  - filter_expr

Environment Variables

MILVUS_URI: Milvus server URI (alternative to --milvus-uri)
MILVUS_TOKEN: Optional authentication token
MILVUS_DB: Database name (defaults to "default")

Development

Run the server directly:

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

Examples

Using Claude Desktop

Example 1: Listing Collections

Query:

What are the collections I have in my Milvus DB?

Response:

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

Query:

Find documents in my text_collection that mention "machine learning"

Response:

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

Query:

Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)

Response:

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

Verify your Milvus instance is running (e.g., docker ps if using Docker)
Check your URI configuration
Ensure no firewall rules block the connection
Use 127.0.0.1 instead of localhost in the URI

Authentication Issues

If you see authentication errors:

Verify MILVUS_TOKEN is correct
Check if Milvus requires authentication
Confirm you have correct permissions

Tool Not Found

If MCP tools don't show in Claude Desktop or Cursor:

Restart the application
Check server logs
Verify MCP server is running
Press refresh in MCP settings (Cursor)

Getting Help

If issues persist:

Check GitHub Issues
Join the Zilliz Community Discord for support
File a new issue with detailed information