用于 Milvus 的 MCP 服务器

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

此仓库包含一个 MCP 服务器，它提供了对 Milvus 向量数据库功能的访问。

先决条件

在使用此 MCP 服务器之前，请确保你具备以下条件：

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

使用方式

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

如果你想克隆仓库：

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

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

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

支持的应用程序

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

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

与 Claude Desktop 一起使用

1. 从 https://claude.ai/download 安装 Claude Desktop

2. 打开你的 Claude Desktop 配置：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

3. 添加以下配置：

{
  "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 也通过其 Composer 中的 Agent 功能支持 MCP 工具。你可以通过两种方式将 Milvus MCP 服务器添加到 Cursor：

选项 1：使用 Cursor 设置界面

1. 转到 Cursor Settings > Features > MCP

2. 点击 + Add New MCP Server 按钮

3. 填写表单：

   • 类型：选择 stdio（因为你正在运行命令）
   • 名称：milvus
   • 命令：/PATH/TO/uv --directory /path/to/mcp-server-milvus/src/mcp_server_milvus run server.py --milvus-uri http://127.0.0.1:19530

   ⚠️ 注意：使用 127.0.0.1 而不是 localhost，以避免潜在的 DNS 解析问题。

选项 2：使用项目特定配置（推荐）

在项目根目录下创建一个 .cursor/mcp.json 文件：

1. 在项目根目录下创建 .cursor 目录：

   mkdir -p /path/to/your/project/.cursor
   

2. 创建一个 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"
         ]
       }
     }
   }
   

3. 重启 Cursor 或重新加载窗口

添加服务器后，你可能需要按 MCP 设置中的刷新按钮以填充工具列表。当 Composer Agent 与你的查询相关时，它将自动使用 Milvus 工具。

验证集成

要验证 Cursor 是否成功集成了你的 Milvus MCP 服务器：

1. 打开 Cursor Settings > Features > MCP
2. 检查“Milvus”是否出现在 MCP 服务器列表中
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：包含要搜索的向量的字段（默认："vector"）
    • limit：最大结果数（默认：5）
    • output_fields：结果中包含的字段
    • metric_type：距离度量（COSINE、L2、IP）（默认："COSINE"）
    • filter_expr：可选过滤表达式

• milvus-hybrid-search：执行结合向量相似性和属性过滤的混合搜索

  • 参数：
    • collection_name：要搜索的集合名称
    • vector：查询向量
    • vector_field：包含要搜索的向量的字段（默认："vector"")
    • filter_expr：元数据过滤表达式
    • limit：最大结果数（默认：5）
    • output_fields：结果中包含的字段
    • metric_type：距离度量（COSINE、L2、IP）（默认："COSINE"）

• milvus-multi-vector-search：使用多个查询向量执行向量相似性搜索

  • 参数：
    • collection_name：要搜索的集合名称
    • vectors：查询向量列表
    • vector_field：包含要搜索的向量的字段（默认："vector"）
    • limit：每个查询的最大结果数（默认：5）
    • output_fields：结果中包含的字段
    • metric_type：距离度量（COSINE、L2、IP）（默认："COSINE"）
    • filter_expr：可选过滤表达式

• milvus-query：使用过滤表达式查询集合

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

• milvus-count：统计集合中的实体数量

  • 参数：
    • collection_name：集合名称
    • filter_expr：可选过滤表达式

集合管理

• milvus-list-collections：列出数据库中的所有集合

• milvus-collection-info：获取集合的详细信息

  • 参数：
    • collection_name：集合名称

• milvus-get-collection-stats：获取集合的统计信息

  • 参数：
    • collection_name：集合名称

• milvus-create-collection：使用指定模式创建新集合

  • 参数：
    • collection_name：新集合的名称
    • schema：集合模式定义
    • index_params：可选索引参数

• milvus-load-collection：将集合加载到内存中以进行搜索和查询

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

• milvus-release-collection：从内存中释放集合

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

• milvus-get-query-segment-info：获取查询段的信息

  • 参数：
    • collection_name：集合名称

• milvus-get-collection-loading-progress：获取集合的加载进度

  • 参数：
    • collection_name：集合名称

数据操作

• milvus-insert-data：将数据插入集合

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

• milvus-bulk-insert：批量插入数据以提高性能

  • 参数：
    • collection_name：集合名称
    • data：字段名到值列表的映射字典
    • batch_size：每批记录数（默认：1000）

• milvus-upsert-data：将数据插入或更新到集合中（如果存在则更新）

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

• milvus-delete-entities：根据过滤表达式从集合中删除实体

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

• milvus-create-dynamic-field：向现有集合添加动态字段

  • 参数：
    • collection_name：集合名称
    • field_name：新字段的名称
    • data_type：字段的数据类型
    • description：可选描述

索引管理

• milvus-create-index：在向量字段上创建索引

  • 参数：
    • collection_name：集合名称
    • field_name：要索引的字段
    • index_type：索引类型（IVF_FLAT、HNSW 等）（默认："IVF_FLAT"）
    • metric_type：距离度量（COSINE、L2、IP）（默认："COSINE"）
    • params：附加索引参数

• milvus-get-index-info：获取集合中索引的信息

  • 参数：
    • collection_name：集合名称
    • field_name：可选特定字段以获取索引信息

环境变量

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

开发

要直接运行服务器：

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

示例

使用 Claude Desktop

示例 1：列出集合

我的 Milvus 数据库中有哪些集合？

Claude 将使用 MCP 在我们的 Milvus 数据库上检查此信息。

我将检查你的 Milvus 数据库中有哪些集合。

> 查看来自 milvus-list-collections 的结果，来自 milvus（本地）

以下是你的 Milvus 数据库中的集合：

1. rag_demo
2. test
3. chat_messages
4. text_collection
5. image_collection
6. customized_setup
7. streaming_rag_demo

示例 2：搜索文档

在我的 text_collection 中查找提到“机器学习”的文档

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

我将搜索你的 text_collection 中关于机器学习的文档。

> 查看来自 milvus-text-search 的结果，来自 milvus（本地）

以下是我找到的提到机器学习的文档：
[根据你的实际数据，结果将显示在这里]

使用 Cursor

示例：创建集合

在 Cursor 的 Composer 中，你可以询问：

在 Milvus 中创建一个名为 'articles' 的新集合，包含 title（字符串）、content（字符串）和一个向量字段（128 维）

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

我将创建一个名为 'articles' 的新集合，包含指定的字段。

> 查看来自 milvus-create-collection 的结果，来自 milvus（本地）

集合 'articles' 已成功创建，模式如下：
- title: 字符串
- content: 字符串
- vector: 浮点向量[128]

故障排除

常见问题

连接错误

如果你看到“无法连接到 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 设置中的刷新按钮（对于 Cursor）

获取帮助

如果你继续遇到问题：

1. 查看 GitHub Issues 是否有类似问题
2. 加入 Zilliz Community Discord 获取支持
3. 提交一个新问题，并提供有关你问题的详细信息