MCP 服务器

MCP Server for Milvus

用于 Milvus 的模型上下文协议服务器

stephen37

研究与数据

README

用于 Milvus 的 MCP 服务器

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

此存储库包含一个 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: AI 驱动的代码编辑器，其 Composer 功能支持 MCP
自定义 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 还通过其 Composer 中的 Agent 功能支持 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 设置中按刷新按钮以填充工具列表。 Composer 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”）
  - 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 (local) 的 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 中查找提及“machine learning”的文档

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

我将在您的 text_collection 中搜索有关机器学习的文档。

> 查看来自 milvus (local) 的 milvus-text-search 的结果

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

使用 Cursor

示例：创建集合

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

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

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

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

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

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

故障排除

常见问题

连接错误

如果您看到类似“Failed to connect to Milvus server”的错误：

验证您的 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