milvus-sdk-code-helper
A Model Context Protocol server that retrieves relevant code snippets or documents to help generating pymilvus code.
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)
Quick Start with FastMCP
The recommended way to use this MCP server is through FastMCP, which provides better performance and easier configuration.
First Time Setup (with Document Update)
For the first time running the server, use the main FastMCP server which will automatically update the document database:
uv run src/mcp_pymilvus_code_generate_helper/fastmcp_server.py
This will:
- Connect to your Milvus instance (default: http://localhost:19530)
- Download and process the latest Milvus documentation
- Start the MCP server with all three tools available
Custom Configuration
# Connect to remote Milvus server
uv run src/mcp_pymilvus_code_generate_helper/fastmcp_server.py --milvus_uri http://your-server:19530 --milvus_token your_token
# Change server host and port
uv run src/mcp_pymilvus_code_generate_helper/fastmcp_server.py --host 0.0.0.0 --port 8080
# Use different transport (default is http)
uv run src/mcp_pymilvus_code_generate_helper/fastmcp_server.py --transport sse
Subsequent Runs (Lightweight Mode)
After the initial setup, you can use the lightweight FastMCP server for faster startup:
uv run examples/fastmcp_server.py
This lightweight version:
- Skips document synchronization
- Starts immediately without background tasks
- Assumes documents are already loaded in Milvus
Lightweight Server Options
# Custom configuration for lightweight server
uv run examples/fastmcp_server.py --milvus_uri http://your-server:19530 --host 0.0.0.0 --port 8080 --transport http
Key Features
- Automatically fetches and indexes the latest Milvus documentation version (可以获取最新文档版本)
- Weekly auto-refresh via a lightweight background scheduler
Usage with Cursor
- Go to
Cursor>Settings>MCP - Click on the
+ Add New Global MCP Serverbutton - Configure based on your chosen mode:
For HTTP Transport (Recommended)
{
"mcpServers": {
"milvus-sdk-code-helper": {
"url": "http://localhost:8000/mcp"
}
}
}
For SSE Transport
{
"mcpServers": {
"milvus-sdk-code-helper": {
"url": "http://localhost:8000"
}
}
}
For STDIO Transport
{
"mcpServers": {
"milvus-sdk-code-helper": {
"command": "/PATH/TO/uv",
"args": [
"--directory",
"/path/to/milvus-sdk-code-helper",
"run",
"examples/fastmcp_server.py",
"--transport",
"stdio",
"--milvus_uri",
"http://localhost:19530"
],
"env": {
"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
}
}
}
}
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 - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Add the following configuration:
For HTTP Transport
{
"mcpServers": {
"milvus-sdk-code-helper": {
"url": "http://localhost:8000/mcp"
}
}
}
For STDIO Transport
{
"mcpServers": {
"milvus-sdk-code-helper": {
"command": "/PATH/TO/uv",
"args": [
"--directory",
"/path/to/milvus-sdk-code-helper",
"run",
"examples/fastmcp_server.py",
"--transport",
"stdio",
"--milvus_uri",
"http://localhost:19530"
],
"env": {
"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
}
}
}
}
- Restart Claude Desktop
⚠️ Note: Remember to set the
OPENAI_API_KEYenvironment variable when using STDIO transport.
Usage with Claude Code (VS Code)
Using CLI (Recommended)
# HTTP (recommended)
claude mcp add --transport http milvus-sdk-code-helper http://localhost:8000/mcp
# SSE
claude mcp add --transport sse milvus-sdk-code-helper http://localhost:8000
# STDIO
claude mcp add milvus-sdk-code-helper /ABS/PATH/TO/uv -- \
--directory /ABS/PATH/TO/milvus-sdk-code-helper \
run examples/fastmcp_server.py --transport stdio --milvus_uri http://localhost:19530
Manual Configuration
- Global (
~/.claude.json) – HTTP transport
{
"mcpServers": {
"milvus-sdk-code-helper": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
- Project (
.mcp.jsonat project root) – STDIO transport
{
"mcpServers": {
"milvus-sdk-code-helper": {
"type": "stdio",
"command": "/ABS/PATH/TO/uv",
"args": [
"--directory",
"/ABS/PATH/TO/milvus-sdk-code-helper",
"run",
"examples/fastmcp_server.py",
"--transport",
"stdio",
"--milvus_uri",
"http://localhost:19530"
],
"env": {
"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
}
}
}
}
Usage with Gemini CLI (as an MCP server)
You can add a Gemini MCP server alongside this project in the same client. This is optional and independent of this server.
Available Tools
The server provides three powerful tools for Milvus code generation and translation:
1. milvus_code_generator
Generate or provide sample PyMilvus/Milvus code based on natural language input.
- When to use: Code generation, sample code requests, "how to write" queries
- Parameters:
query: Your natural language request for code generation
- Example: "Generate pymilvus code for hybrid search"
2. orm_client_code_convertor
Convert between ORM and PyMilvus client code formats.
- When to use: Converting between ORM and client styles, format adaptation
- Parameters:
query: List of Milvus API names to convert (e.g.,["create_collection", "insert"])
- Example: "Convert ORM code to PyMilvus client"
3. milvus_code_translator
Translate Milvus code between different programming languages.
- When to use: Cross-language code translation
- Parameters:
query: List of Milvus API names in escaped double quotes format (e.g.,[\"create_collection\", \"insert\", \"search\"])source_language: Source programming language (python, java, go, csharp, node, restful)target_language: Target programming language (python, java, go, csharp, node, restful)
- Example: "Translate Python Milvus code to Java"
⚠️ Important: You don't need to specify tool names or parameters manually. Just describe your requirements naturally, and the MCP system will automatically select the appropriate tool and prepare the necessary parameters.
Legacy Transport Modes
For backward compatibility, the server also supports SSE and STDIO transport modes:
SSE Transport
# Start SSE server
uv run src/mcp_pymilvus_code_generate_helper/sse_server.py --milvus_uri http://localhost:19530
# Cursor configuration for SSE
{
"mcpServers": {
"milvus-sdk-code-helper": {
"url": "http://localhost:23333/milvus-code-helper/sse"
}
}
}
STDIO Transport
# Start STDIO server
uv run src/mcp_pymilvus_code_generate_helper/stdio_server.py --milvus_uri http://localhost:19530
# Cursor configuration for STDIO
{
"mcpServers": {
"milvus-sdk-code-helper": {
"command": "/PATH/TO/uv",
"args": [
"--directory",
"/path/to/milvus-sdk-code-helper",
"run",
"src/mcp_pymilvus_code_generate_helper/stdio_server.py",
"--milvus_uri",
"http://localhost:19530"
],
"env": {
"OPENAI_API_KEY": "YOUR_OPENAI_API_KEY"
}
}
}
}
Docker Support
You can also run the server using Docker:
Build the Docker Image
docker build -t milvus-code-helper .
Run with FastMCP (Recommended)
# First time run with document update
docker run -p 8000:8000 \
-e OPENAI_API_KEY=your_openai_key \
-e MILVUS_URI=http://your-milvus-host:19530 \
-e MILVUS_TOKEN=your_milvus_token \
milvus-code-helper
# Lightweight mode for subsequent runs
docker run -p 8000:8000 \
-e OPENAI_API_KEY=your_openai_key \
-e MILVUS_URI=http://your-milvus-host:19530 \
-e MILVUS_TOKEN=your_milvus_token \
milvus-code-helper examples/fastmcp_server.py
Configuration Options
Server Parameters
| Parameter | Description | Default |
|---|---|---|
--milvus_uri | Milvus server URI | http://localhost:19530 |
--milvus_token | Milvus authentication token | "" |
--db_name | Milvus database name | default |
--host | Server host address | 0.0.0.0 |
--port | Server port | 8000 |
--path | HTTP endpoint path | /mcp |
--transport | Transport protocol | http |
Transport Options
http: RESTful HTTP transport (recommended)sse: Server-Sent Events transportstdio: Standard input/output transport
Environment Variables
OPENAI_API_KEY: Required for document processing and embedding generationMILVUS_URI: Alternative way to specify Milvus server URIMILVUS_TOKEN: Alternative way to specify Milvus authentication token
Troubleshooting
Common Issues
- Connection refused: Ensure Milvus is running and accessible
- Authentication failed: Check your Milvus token and credentials
- Port conflicts: Change the port using
--portparameter - Missing documents: Run the full server first to populate the database
Debug Mode
Enable debug logging:
PYTHONPATH=src python -m logging --level DEBUG src/mcp_pymilvus_code_generate_helper/fastmcp_server.py
Contributing
Contributions are welcome! If you have ideas for improving the retrieval results or adding new features, please submit a pull request or open an issue.
License
This project is licensed under the MIT License.