Milvus MCP Server

官方

在您的Milvus向量数据库中搜索、查询和交互数据。

GitHub
233

文档

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

运行模式

服务器支持两种运行模式：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...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀

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

可流式 HTTP 模式

  • 描述：使用支持流式传输的 HTTP 进行通信。这是生产部署的推荐传输方式，支持有状态和无状态操作。

  • 用法：

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://localhost:19530 --port 8000
    • --streamable-http：启用可流式 HTTP 模式。
    • --port：指定服务器的端口（默认：8000）。
    • --stateless：无状态模式的可选标志（无会话持久性）。

  • 无状态模式：

    uv run src/mcp_server_milvus/server.py --streamable-http --stateless --milvus-uri http://localhost:19530 --port 8000

支持的应用程序

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

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

与 Claude Desktop 一起使用

不同模式的配置

SSE 模式配置

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

  1. 从 https://claude.ai/download. 安装 Claude Desktop
  2. 打开您的 Claude Desktop 配置文件：
    • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  3. 为 SSE 模式添加以下配置：
{
  "mcpServers": {
    "milvus-sse": {
      "url": "http://your_sse_host:port/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

可流式 HTTP 模式配置

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}
  1. 重启 Claude Desktop 以应用更改。

Stdio 模式配置

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

  1. 从 https://claude.ai/download. 安装 Claude Desktop
  2. 打开您的 Claude Desktop 配置文件：
    • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  3. 为 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"
      ]
    }
  }
}
  1. 重启 Claude Desktop 以应用更改。

与 Cursor 一起使用

Cursor 也支持 MCP 工具。您可以按照以下步骤将您的 Milvus MCP 服务器与 Cursor 集成：

集成步骤

  1. 打开 Cursor Settings > MCP
  2. 点击 Add new global MCP server
  3. 点击后，它将自动重定向您到 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 模式：

  1. 通过运行以下命令启动服务：

    uv run src/mcp_server_milvus/server.py --sse --milvus-uri http://your_sse_host --port port

    注意：将 http://your_sse_host 替换为您实际的 SSE 主机地址，将 port 替换为您正在使用的特定端口号。

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

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

对于可流式 HTTP 模式：

  1. 启动服务：

    uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port

  2. 更新 mcp.json：

    {
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

完成集成

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

验证集成

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

  1. 打开 Cursor Settings > MCP
  2. 检查列表中是否出现 "milvus"、"milvus-sse" 或 "milvus-streamable-http"（取决于您选择的模式）
  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）（默认：0.2）

  • milvus_vector_search：在集合上执行向量相似性搜索

    • 参数：
      • collection_name：要搜索的集合名称
      • vector：查询向量
      • vector_field：向量搜索的字段名称（默认："vector"）
      • limit：要返回的最大结果数（默认：5）
      • output_fields：要包含在结果中的字段
      • filter_expr：过滤表达式
      • metric_type：距离度量（COSINE、L2、IP）（默认："COSINE"）
      • radius：范围搜索的可选下限（默认：None）
      • range_filter：范围搜索的可选上限（默认：None）

  • milvus_hybrid_search：在集合上执行混合搜索

    • 参数：
      • collection_name：要搜索的集合名称
      • query_text：用于搜索的文本查询
      • text_field：文本搜索的字段名称
      • vector：文本查询的向量
      • vector_field：向量搜索的字段名称
      • limit：要返回的最大结果数（默认：5）
      • output_fields：要包含在结果中的字段
      • filter_expr：过滤表达式
      • sparse_radius：稀疏范围搜索的可选下限（默认：None）
      • sparse_range_filter：稀疏范围搜索的可选上限（默认：None）
      • dense_radius：稠密范围搜索的可选下限（默认：None）
      • dense_range_filter：稠密范围搜索的可选上限（默认：None）

  • milvus_text_similarity_search：在集合上执行文本相似性搜索

    注意：此工具仅在 Milvus 2.6.0 及以上版本中受支持。并且您需要在 Milvus 服务器上设置嵌入函数。有关更多详细信息，请参阅 嵌入函数。

    • 参数：
      • collection_name：要搜索的集合名称
      • query_text：用于相似性搜索的文本查询
      • anns_field：文本搜索的字段名称
      • limit：要返回的最大结果数（默认：5）
      • output_fields：要包含在结果中的字段
      • metric_type：距离度量（COSINE、L2、IP）（默认："COSINE"）
      • filter_expr：可选的过滤表达式
      • radius：范围搜索的可选下限（默认：None）
      • range_filter：范围搜索的可选上限（默认：None）

  • milvus_query：使用过滤表达式查询集合

    • 参数：
      • collection_name：要查询的集合名称
      • filter_expr：过滤表达式（例如 'age > 20'）
      • output_fields：要包含在结果中的字段
      • limit：要返回的最大结果数（默认：10）

集合管理

  • milvus_list_collections：列出数据库中的所有集合

  • milvus_create_collection：使用快速设置或自定义模式创建新集合

    • 参数：
      • collection_name：新集合的名称
      • auto_id：是否自动生成 ID，默认为 True
      • dimension：向量维度，默认为 768；用于快速设置，如果提供了 field_schema，将被忽略
      • primary_field_name：主字段的名称，默认为 "id"；用于快速设置，如果提供了 field_schema，将被忽略
      • vector_field_name：向量字段的名称，默认为 "vector"；用于快速设置，如果提供了 field_schema，将被忽略
      • metric_type：度量类型，默认为 "COSINE"；用于快速设置，如果提供了 field_schema，将被忽略
      • field_schema：字段模式列表，每个元素是一个包含以下键的字典：
        • name：字段名称
        • type：字段类型
      • index_params：可选的索引参数列表，每个元素是一个包含以下键的字典：
        • field_name：要索引的字段名称
        • index_type：索引类型
        • **kwargs：其他可选的索引参数
      • other_kwargs：用于集合创建的额外关键字参数

  • 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：列出集合

What are the collections I have in my Milvus DB?

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

I'll check what collections are available in your Milvus database.

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 中，您可以询问：

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.

Collection 'articles' has been created successfully with the following schema:
- title: string
- content: string
- vector: float vector[128]

故障排除

常见问题

连接错误

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

  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. 加入 Milvus 社区 Discord 寻求支持
  3. 提交一个新 issue，并提供有关您问题的详细信息