MCP Server for Milvus

模型上下文协议（MCP）是一种开放协议，它使大型语言模型（LLM）应用程序与外部数据源和工具之间的无缝集成成为可能。无论您是构建AI驱动的IDE、增强聊天界面，还是创建自定义AI工作流，MCP都提供了一种标准化的方法来连接LLMs及其所需的上下文。

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

使用前提

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

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

使用方法

推荐的使用此MCP服务器的方式是直接使用uv运行而不进行安装。这是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客户端规范的应用程序

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

选项1：使用Cursor设置UI

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 DB中有哪些集合？

Claude将使用MCP检查这些信息：

我将检查您Milvus数据库中可用的集合。

> 查看来自milvus-list-collections的结果

以下是您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的结果

我找到了提到机器学习的文档：
[基于您的实际数据的结果将在此处出现]

使用Cursor

示例：创建集合

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

在Milvus中创建一个名为'articles'的新集合，带有标题（字符串）、内容（字符串）和一个向量字段（128维）

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

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

> 查看来自milvus-create-collection的结果

'articles'集合已成功创建，具有以下模式：
- 标题：字符串
- 内容：字符串
- 向量：浮点向量[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社区Discord寻求支持
3. 提交一份包含详细问题信息的新问题