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/stephen37/mcp-server-milvus.git
cd mcp-server-milvus

然后即可直接运行服务：

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

支持的应用

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

• Claude Desktop：Anthropic 为 Claude 提供的桌面应用
• Cursor：一款由 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. 检查 MCP 服务列表中是否显示“Milvus”
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：列出集合

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.

> View result from milvus-list-collections from milvus (local)

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 的 Composer 中，你可以这样提问：

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.

> View result from milvus-create-collection from milvus (local)

Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float 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. 提交新问题，并详细说明遇到的问题