MCP Server for Milvus

Milvus MCP 服务

模型上下文协议（MCP）是一种开放协议，可让大模型应用与外部数据源和工具无缝集成。无论你是在构建 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都能提供一种标准化方式，将大模型与其所需的上下文连接起来。

此仓库包含一个 MCP 服务，可用于访问 Milvus 向量数据库功能。

前提条件

使用此 MCP 服务之前，请确保你具备：

• Python 3.10 或更高版本
• 正在运行的 Milvus 实例（本地或远程）
• 已安装 uv（推荐用于运行服务）

用法

推荐的使用方式是直接通过 uv 运行此 MCP 服务，无需安装。下文示例中，Claude Desktop 和 Cursor 均采用此方式进行配置。

如果你想克隆此仓库：

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

然后可以直接运行服务：

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

或者，你可以修改 src/mcp_server_milvus/ 目录中的 .env 文件来设置环境变量，并使用以下命令运行服务：

uv run src/mcp_server_milvus/server.py

重要提示：.env 文件的优先级高于命令行参数。

运行模式

此服务支持两种运行模式：stdio（默认）和 SSE（服务器发送事件）。

Stdio 模式（默认）

• 说明：通过标准输入/输出与客户端通信。如果未指定模式，则默认使用此模式。

• 用法：

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

SSE 模式

• 说明：使用 HTTP 服务器发送事件进行通信。此模式允许多个客户端通过 HTTP 连接，适用于基于 Web 的应用。

• 用法：

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

  • --sse：启用 SSE 模式。
  • --port：指定 SSE 服务的端口（默认值：8000）。

• 在 SSE 模式下调试：

  如果想在 SSE 模式下调试，请在启动 SSE 服务后输入以下命令：

  mcp dev src/mcp_server_milvus/server.py
  

  输出内容类似于：

  % 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 🚀
  

  然后，你可以访问 http://127.0.0.1:6274 中的 MCP Inspector 进行测试。

Streamable HTTP 模式

• 说明：使用支持流式传输的 HTTP 进行通信。这是生产部署的推荐传输方式，同时支持有状态和无状态运行。

• 用法：

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

  • --streamable-http：启用 Streamable HTTP 模式。
  • --port：指定服务的端口（默认值：8000）。
  • --stateless：无状态模式的可选标志（不保留会话）。

• 无状态模式：

  uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000
  

支持的应用

此 MCP 服务可与各种支持模型上下文协议的大模型应用搭配使用：

• Claude Desktop：Anthropic 为 Claude 提供的桌面应用
• Cursor：支持 MCP 的 AI 驱动代码编辑器
• 自定义 MCP 客户端：任何实现 MCP 客户端规范的应用

在 Claude Desktop 中使用

不同模式的配置

SSE 模式配置

按照以下步骤为 SSE 模式配置 Claude Desktop：

1. 从 https://claude.ai/download 安装 Claude Desktop。
2. 打开 Claude Desktop 配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
3. 添加以下 SSE 模式配置：

{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Streamable HTTP 模式配置

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

4. 重启 Claude Desktop 以应用更改。

Stdio 模式配置

按照以下步骤配置 stdio 模式：

1. 从 https://claude.ai/download 安装 Claude Desktop。
2. 打开 Claude Desktop 配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
3. 添加以下 stdio 模式配置：

{
  "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. 重启 Claude Desktop 以应用更改。

在 Cursor 中使用

Cursor 也支持 MCP 工具。按照以下步骤，即可将 Milvus MCP 服务集成到 Cursor：

集成步骤

1. 打开 Cursor Settings > MCP
2. 点击 Add new global MCP server
3. 点击后，系统会自动跳转到 mcp.json 文件；如果该文件不存在，系统会创建它

配置 mcp.json 文件

对于 Stdio 模式：

用以下内容覆盖 mcp.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"
      ]
    }
  }
}

对于 SSE 模式：

1. 运行以下命令启动服务：

   uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
   

   注意：将 http://your_sse_host 替换为实际的 SSE 主机地址，并将 port 替换为你使用的具体端口号。

2. 服务启动并运行后，用以下内容覆盖 mcp.json 文件：

   {
       "mcpServers": {
         "milvus-sse": {
           "url": "http://your_sse_host:port/sse",
           "disabled": false,
           "autoApprove": []
         }
       }
   }
   

对于 Streamable HTTP 模式：

1. 启动服务：

   uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port
   

2. 更新 mcp.json：

   {
     "mcpServers": {
       "milvus-streamable-http": {
         "url": "http://your_host:port/mcp",
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

完成集成

完成上述步骤后，重启 Cursor 或重新加载窗口，以确保配置生效。

验证集成

若要验证 Cursor 是否已成功集成 Milvus MCP 服务：

1. 打开 Cursor Settings > MCP
2. 检查列表中是否出现“milvus”“milvus-sse”或“milvus-streamable-http”（具体取决于所选模式）
3. 确认列表中包含相关工具（例如，milvus_list_collections、milvus_vector_search 等）
4. 如果服务已启用但显示错误，请查看下方的故障排除部分

可用工具

该服务提供以下工具：

搜索和查询操作

• milvus_text_search：使用全文搜索查找文档

  • 参数：
    • collection_name：要搜索的集合名称
    • query_text：要搜索的文本
    • limit：返回结果的最大数量（默认值：5）
    • output_fields：结果中要包含的字段
    • drop_ratio：要忽略的低频词比例（0.0-1.0）（默认值：0.2）

• milvus_vector_search：对集合执行向量相似度搜索

  • 参数：
    • collection_name：要搜索的集合名称
    • vector：查询向量
    • vector_field：向量搜索的字段名称（默认值："vector"）
    • limit：返回结果的最大数量（默认值：5）
    • output_fields：结果中要包含的字段
    • filter_expr：过滤表达式
    • metric_type：距离度量（COSINE、L2、IP）（默认值："COSINE"）
    • radius：范围搜索的可选下限（默认值：None）
    • range_filter：范围搜索的可选上限（默认值：None）

• milvus_hybrid_search：对集合执行混合搜索

  • 参数：
    • collection_name：要搜索的集合名称
    • query_text：用于搜索的文本查询
    • text_field：文本搜索的字段名称
    • vector：文本查询的向量
    • vector_field：向量搜索的字段名称
    • limit：返回结果的最大数量（默认值：5）
    • output_fields：结果中要包含的字段
    • filter_expr：过滤表达式
    • sparse_radius：稀疏范围搜索的可选下限（默认值：None）
    • sparse_range_filter：稀疏范围搜索的可选上限（默认值：None）
    • dense_radius：稠密范围搜索的可选下限（默认值：None）
    • dense_range_filter：稠密范围搜索的可选上限（默认值：None）

• milvus_text_similarity_search：对集合执行文本相似度搜索

  注意：此工具仅支持 Milvus 2.6.0 及以上版本。你还需要在 Milvus 服务端设置嵌入函数。详情请参阅 嵌入函数。

  • 参数：
    • collection_name：要搜索的集合名称
    • query_text：用于相似度搜索的文本查询
    • anns_field：文本搜索的字段名称
    • limit：返回结果的最大数量（默认值：5）
    • output_fields：结果中要包含的字段
    • metric_type：距离度量（COSINE、L2、IP）（默认值："COSINE"）
    • filter_expr：可选的过滤表达式
    • radius：范围搜索的可选下限（默认值：None）
    • range_filter：范围搜索的可选上限（默认值：None）

• milvus_query：使用过滤表达式查询集合

  • 参数：
    • collection_name：要查询的集合名称
    • filter_expr：过滤表达式（例如：'age > 20'）
    • output_fields：结果中要包含的字段
    • limit：返回结果的最大数量（默认值：10）

集合管理

• milvus_list_collections：列出数据库中的所有集合

• milvus_create_collection：使用快速设置或自定义架构创建新集合

  • 参数：
    • collection_name：新集合的名称
    • auto_id：是否自动生成 ID，默认为 True
    • dimension：向量维度，默认为 768；用于快速设置，若提供了 field_schema 则会被忽略
    • primary_field_name：主字段的名称，默认为 "id"；用于快速设置，若提供了 field_schema 则会被忽略
    • vector_field_name：向量字段的名称，默认为 "vector"；用于快速设置，若提供了 field_schema 则会被忽略
    • metric_type：度量类型，默认为 "COSINE"；用于快速设置，若提供了 field_schema 则会被忽略
    • field_schema：字段架构列表，每个元素都是一个包含以下键的字典：
      • name：字段名称
      • type：字段类型
    • index_params：可选的索引参数列表，每个元素都是一个包含以下键的字典：
      • field_name：要建立索引的字段名称
      • index_type：索引类型
      • **kwargs：其他可选索引参数
    • other_kwargs：创建集合时使用的其他关键字参数

• milvus_load_collection：将集合加载到内存中，以便进行搜索和查询

  • 参数：
    • collection_name：要加载的集合名称
    • replica_number：副本数量（默认值：1）

• milvus_release_collection：从内存中释放集合

  • 参数：
    • collection_name：要释放的集合名称

• milvus_get_collection_info：列出特定集合的详细信息，例如架构、属性、集合 ID 和其他元数据。

  • 参数：
    • collection_name：要获取详细信息的集合名称

数据操作

• milvus_insert_data：向集合中插入数据

  • 参数：
    • collection_name：集合名称
    • data：将字段名称映射到值列表的字典

• milvus_delete_entities：根据筛选表达式从集合中删除实体

  • 参数：
    • collection_name：集合名称
    • filter_expr：用于选择要删除实体的筛选表达式

环境变量

• MILVUS_URI：Milvus 服务 URI（可替代 --milvus-uri 设置）
• MILVUS_TOKEN：可选的身份验证令牌
• MILVUS_DB：数据库名称（默认为 "default"）

开发

要直接运行服务：

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

示例

使用 Claude Desktop

示例 1：列出集合

What are the collections I have in my Milvus DB?

随后，Claude 将使用 MCP 在你的 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

示例 2：搜索文档

Find documents in my text_collection that mention "machine learning"

Claude 将使用 Milvus 的全文搜索功能查找相关文档：

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]

使用 Cursor

示例：创建集合

在 Cursor 中，你可以这样提问：

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

Cursor 将使用 MCP 服务执行此操作：

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]

故障排除

常见问题

连接错误

如果看到类似 "Failed to connect to Milvus server" 的错误：

1. 确认 Milvus 实例正在运行：docker ps（如果使用 Docker）
2. 检查配置中的 URI 是否正确
3. 确保没有防火墙规则阻止连接
4. 尝试在 URI 中使用 127.0.0.1 代替 localhost

身份验证问题

如果看到身份验证错误：

1. 确认 MILVUS_TOKEN 正确
2. 检查 Milvus 实例是否要求身份验证
3. 确保你拥有执行所尝试操作所需的正确权限

未找到工具

如果 MCP 工具未显示在 Claude Desktop 或 Cursor 中：

1. 重启应用程序
2. 检查服务日志中是否有错误
3. 确认 MCP 服务正在正常运行
4. 在 MCP 设置中按下刷新按钮（适用于 Cursor）

获取帮助

如果问题仍然存在：

1. 查看 GitHub Issues，寻找类似问题
2. 加入 Milvus Community Discord 获取支持
3. 提交新问题，并详细说明遇到的问题