Milvus MCP Server

🚀 Compatible Milvus MCP Server for Claude

This repository provides all the necessary components to connect Anthropic's Claude (via Claude Desktop) to the Milvus vector database through MCP (Model Context Protocol). It includes:

• 🧠 A fully FastMCP-compatible server
• 🗃️ Milvus setup (via Docker)
• 🛠️ Shell scripts to start the server for use with Claude
• ✅ Official Milvus tool names to ensure compatibility with Claude

📦 Folder Structure

.
├── milvus-standalone/                 # Contains Docker Compose for Milvus
│   ├── docker-compose.yml
│   └── config/                        # Milvus etcd configuration files (if needed)
├── fastmcp/
│   ├── milvus-server/                # Your custom MCP server files
│   │   ├── server.py                 # MCP server code
│   │   └── run_milvus_server.sh     # Startup script for Claude
│   ├── .venv/                        # Python virtual environment managed by uv
│   └── pyproject.toml                # FastMCP + dependencies
├── claude_desktop_config.json        # Add this entry to the Claude configuration
└── README.md

🚀 Quick Start

Step 1: Clone the repository

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

Step 2: Run Milvus (Docker)

Make sure Docker is installed and running.

cd milvus-standalone
docker-compose up -d

Step 3: Install uv (if you haven't already)

brew install uv

Step 4: Synchronize the Python environment

Navigate to the fastmcp/ directory:

cd fastmcp
uv sync

Step 5: Test the server

uv run python milvus-server/server.py

You should see logs similar to the following:

INFO: Connected to Milvus
✅ Server loaded and tools registered

Step 6: Update the Claude configuration

Update claude_desktop_config.json as follows:

{
  "milvus": {
    "command": "/full/path/to/run_milvus_server.sh",
    "args": []
  }
}

Make sure to restart Claude after the update.

Step 7: Run Claude

Try:

"Invoke the Milvus tool to list all collections."

It should now connect and execute.

🧠 Tool Naming Rules (Crucial!)

Claude only recognizes tools that exactly match the Milvus naming convention. Do not rename the tools. Use:

create_collection

list_collections

search

etc.

In the code, use @mcp.tool(name="create_collection"), and the names are case-sensitive.

🧪 Debugging Tips

• Ensure that the Milvus Docker container is running healthily (docker ps).
• Check the FastMCP server logs.
• Add print statements in the tools for debugging.
• Ensure the use of a consistent .venv and uv environment.
• Do not use emojis or non-ASCII characters in the tool descriptions.

📌 Next Steps

• Add more tools (delete_collection, upsert, etc.).
• Add test scripts (test_server.py).
• Add GitHub Actions for verification.

🧪 Testing

To manually run tool tests, use test_server_full.py or the Claude Desktop interface.

🤝 Contributors

• Development: @TerrysPOV
• Support: FastMCP
• Vector storage in Milvus
• Embedding via OpenAI (text-embedding-ada-002)

📄 License

MIT