MCP 服务器

MCP Server for Milvus

一个实现了模型上下文协议的集成服务器，它使LLM应用程序能够与Milvus向量数据库功能进行交互，从而可以通过自然语言进行向量搜索、集合管理和数据操作。

README

用于 Milvus 的 MCP 服务器

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

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

MCP with Milvus

前提条件

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

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

用法

推荐使用此 MCP 服务器的方法是直接使用 uv 运行它，而无需安装。以下示例中，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 文件将比命令行参数具有更高的优先级。

支持的应用程序

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

Claude Desktop: Anthropic 的 Claude 桌面应用程序
Cursor: 具有 MCP 支持的 AI 驱动的代码编辑器
自定义 MCP 客户端: 任何实现 MCP 客户端规范的应用程序

与 Claude Desktop 一起使用

从 https://claude.ai/download 安装 Claude Desktop
打开您的 Claude Desktop 配置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
添加以下配置：

{
  "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"
      ]
    }
  }
}

重启 Claude Desktop

与 Cursor 一起使用

Cursor 也支持 MCP 工具。您可以通过两种方式将 Milvus MCP 服务器添加到 Cursor：

选项 1：使用 Cursor 设置 UI

转到 Cursor Settings > Features > MCP
单击 + Add New MCP Server 按钮
填写表格：
- Type: 选择 stdio（因为您正在运行命令）
- Name: milvus
- Command: /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 文件：

在您的项目根目录中创建 .cursor 目录：
```
mkdir -p /path/to/your/project/.cursor
```

创建一个包含以下内容的 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"
      ]
    }
  }
}

重启 Cursor 或重新加载窗口

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

验证集成

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

打开 Cursor Settings > Features > MCP
检查 "Milvus" 是否出现在 MCP 服务器列表中
验证工具是否已列出（例如，milvus_list_collections、milvus_vector_search 等）
如果服务器已启用但显示错误，请查看下面的“故障排除”部分

可用工具

该服务器提供以下工具：

搜索和查询操作

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”）
milvus_query: 使用过滤器表达式查询集合
- 参数：
  - collection_name: 要查询的集合的名称
  - filter_expr: 过滤器表达式（例如 'age > 20'）
  - output_fields: 要包含在结果中的字段
  - limit: 最大结果数（默认值：10）

集合管理

milvus_list_collections: 列出数据库中的所有集合
milvus_create_collection: 创建具有指定模式的新集合
- 参数：
  - collection_name: 新集合的名称
  - collection_schema: 集合模式定义
  - index_params: 可选索引参数
milvus_load_collection: 将集合加载到内存中以进行搜索和查询
- 参数：
  - collection_name: 要加载的集合的名称
  - replica_number: 副本数（默认值：1）
milvus_release_collection: 从内存中释放集合
- 参数：
  - 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：列出集合

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

然后 Claude 将使用 MCP 来检查您的 Milvus 数据库上的此信息。

我将检查您的 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 (local) 的 milvus-text-search 的结果

以下是我找到的提及机器学习的文档：
[结果将根据您的实际数据出现在此处]

使用 Cursor

示例：创建集合

在 Cursor 中，您可以询问：

在 Milvus 中创建一个名为“articles”的新集合，其中包含标题（字符串）、内容（字符串）和一个向量字段（128 维）

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

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

集合“articles”已成功创建，具有以下模式：
- title: string
- content: string
- vector: float vector[128]

故障排除

常见问题

连接错误

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

验证您的 Milvus 实例是否正在运行：docker ps（如果使用 Docker）
检查您的配置中的 URI 是否正确
确保没有防火墙规则阻止连接
尝试在 URI 中使用 127.0.0.1 而不是 localhost

身份验证问题

如果您看到身份验证错误：

验证您的 MILVUS_TOKEN 是否正确
检查您的 Milvus 实例是否需要身份验证
确保您具有执行您尝试执行的操作的正确权限

未找到工具

如果 MCP 工具未出现在 Claude Desktop 或 Cursor 中：

重启应用程序
检查服务器日志中是否有任何错误
验证 MCP 服务器是否正在正确运行
按 MCP 设置中的刷新按钮（对于 Cursor）

获得帮助

如果您继续遇到问题：

检查 GitHub Issues 中是否有类似的问题
加入 Zilliz Community Discord 以获得支持
提交一个包含有关您的问题的详细信息的新 issue