MCP Server for Milvus

Milvus 的 MCP 服务器

模型上下文协议 (MCP) 是一种开放协议，支持 LLM 应用程序与外部数据源和工具之间的无缝集成。无论您是构建 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都提供了一种标准化的方式，将 LLM 与其所需的上下文连接起来。

该存储库包含一个 MCP 服务器，可提供对Milvus矢量数据库功能的访问。

先决条件

在使用此 MCP 服务器之前，请确保您已：

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

用法

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

如果你想克隆存储库：

然后就可以直接运行服务器了：

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

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

运行模式

服务器支持两种运行模式： stdio （默认）和SSE （Server-Sent Events）。

标准输入输出模式（默认）

• 描述：通过标准输入/输出与客户端通信。如果未指定模式，则此模式为默认模式。
• 用法：
  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 进行测试。

支持的应用程序

此 MCP 服务器可与支持模型上下文协议的各种 LLM 应用程序一起使用：

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

与 Claude Desktop 一起使用

不同模式的配置

SSE模式配置

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

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

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 模式添加以下配置：

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

与游标一起使用

Cursor 也支持 MCP工具。您可以按照以下步骤将 Milvus MCP 服务器与 Cursor 集成：

集成步骤

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

配置mcp.json文件

对于 Stdio 模式：

使用以下内容覆盖mcp.json文件：

对于 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": [] } } }

完成集成

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

验证集成

要验证 Cursor 是否已成功与您的 Milvus MCP 服务器集成：

1. 打开Cursor Settings > MCP
2. 检查列表中是否出现“milvus”或“milvus-sse”（取决于您选择的模式）
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）
• milvus_vector_search ：对集合执行向量相似性搜索
  • 参数：
    • collection_name ：要搜索的集合的名称
    • vector ：查询向量
    • vector_field ：矢量搜索的字段名称（默认值：“矢量”）
    • limit ：返回的最大结果数（默认值：5）
    • output_fields ：结果中包含的字段
    • filter_expr ：过滤表达式
    • metric_type ：距离度量（COSINE，L2，IP）（默认值：“COSINE”）
• milvus_hybrid_search ：对集合执行混合搜索
  • 参数：
    • collection_name ：要搜索的集合的名称
    • query_text ：用于搜索的文本查询
    • text_field ：文本搜索的字段名称
    • vector ：文本查询的向量
    • vector_field ：向量搜索的字段名称
    • limit ：返回结果的最大数量
    • output_fields ：结果中包含的字段
    • filter_expr ：过滤表达式
• milvus_query ：使用过滤表达式查询集合
  • 参数：
    • collection_name ：要查询的集合的名称
    • filter_expr ：过滤表达式（例如“年龄> 20”）
    • output_fields ：结果中包含的字段
    • limit ：返回的最大结果数（默认值：10）

收藏管理

• milvus_list_collections ：列出数据库中的所有集合
• milvus_create_collection ：使用指定的 schema 创建一个新的集合
  • 参数：
    • collection_name ：新集合的名称
    • collection_schema ：集合模式定义
    • index_params ：可选索引参数
• 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”）

发展

直接运行服务器：

示例

使用 Claude Desktop

示例 1：列出集合

然后，Claude 将使用 MCP 在您的 Milvus DB 上检查此信息。

示例 2：搜索文档

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

使用游标

示例：创建集合

在 Cursor 中，你可以询问：

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

故障排除

常见问题

连接错误

如果您看到类似“无法连接到 Milvus 服务器”的错误：

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 设置中的刷新按钮（用于光标）

获取帮助

如果您仍然遇到问题：

1. 查看GitHub Issues 中是否有类似问题
2. 加入Zilliz 社区 Discord以获得支持
3. 提交新问题并提供有关问题的详细信息