Milvus的MCP服务器

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

本仓库包含一个提供Milvus向量数据库功能的MCP服务器。

MCP与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`文件的优先级高于命令行参数。

运行模式

服务器支持两种运行模式：stdio（默认）和SSE（服务器发送事件）。

Stdio模式（默认）

描述：通过标准输入/输出与客户端通信。如果没有指定模式，这是默认模式。

使用方法：

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

SSE模式

描述：使用HTTP服务器发送事件进行通信。此模式允许通过HTTP连接多个客户端，适用于基于Web的应用程序。
使用方法：
```
uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://localhost:19530 --port 8000
```
- --sse：启用SSE模式。
- --port：指定SSE服务器的端口（默认：8000）。

在SSE模式下调试：

如果您想在SSE模式下调试，在启动SSE服务后，输入以下命令：

mcp dev src/mcp_server_milvus/server.py

输出将类似于：

% mcp dev src/mcp_server_milvus/merged_server.py
Starting MCP inspector...
⚙️ 代理服务器监听端口6277
🔍 MCP Inspector已启动并运行于http://127.0.0.1:6274 🚀

然后您可以访问http://127.0.0.1:6274处的MCP Inspector进行测试。

支持的应用程序

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

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

与Claude Desktop一起使用

不同模式的配置

SSE模式配置

按照以下步骤为Claude Desktop配置SSE模式：

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

{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

重启Claude Desktop以应用更改。

Stdio模式配置

对于stdio模式，请按照以下步骤操作：

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

{
  "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集成：

集成步骤

打开Cursor设置 > MCP
点击添加新的全局MCP服务器
点击后，它会自动重定向到mcp.json文件，如果该文件不存在，将会被创建

配置`mcp.json`文件

对于Stdio模式：

用以下内容覆盖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"
      ]
    }
  }
}

对于SSE模式：

通过运行以下命令启动服务：
```
uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port
```
注意：将http://your_sse_host替换为您实际的SSE主机地址，并将port替换为您使用的特定端口号。

一旦服务启动并运行，用以下内容覆盖mcp.json文件：

{
    "mcpServers": {
      "milvus-sse": {
        "url": "http://your_sse_host:port/sse",
        "disabled": false,
        "autoApprove": []
      }
    }
}

完成集成

完成上述步骤后，重启Cursor或重新加载窗口以确保配置生效。

验证集成

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

打开Cursor设置 > MCP
检查"milvus"或"milvus-sse"是否出现在列表中（取决于您选择的模式）
确认相关工具是否列出（例如，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：结果中包含的字段
  - filter_expr：过滤表达式
  - metric_type：距离度量（COSINE、L2、IP）（默认："COSINE"）
milvus_hybrid_search：在集合上执行混合搜索
- 参数：
  - collection_name：要搜索的集合名称
  - query_text：搜索的文本查询
  - text_field：文本搜索的字段名称
  - vector：文本查询的向量
  - vector_field：向量搜索的字段名称
  - limit：要返回的最大结果数
  - output_fields：结果中包含的字段
  - filter_expr：过滤表达式
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_get_collection_info：列出特定集合的详细信息，如模式、属性、集合ID和其他元数据。
- 参数：
  - 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-text-search的结果（来自milvus（本地））

这是我找到的提到机器学习的文档：
[结果将根据您的实际数据出现]

使用Cursor

示例：创建集合

在Cursor中，您可以询问：

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

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

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

集合'articles'已成功创建，具有以下模式：
- 标题：字符串
- 内容：字符串
- 向量：浮点向量[128]

故障排除

常见问题

连接错误

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

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

身份验证错误

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

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

工具未找到

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

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

获取帮助

如果您继续遇到问题：

查看GitHub问题以查找类似问题
加入Zilliz社区Discord以获取支持
提交一个新问题，提供关于您问题的详细信息