MCP + Milvus：连接 AI 与向量数据库

介绍

模型上下文协议（MCP） 是一个开放协议，能够让 AI 应用程序（如 Claude 和 Cursor）无缝地与外部数据源和工具交互。无论您是在构建自定义 AI 应用程序、集成 AI 工作流，还是增强聊天界面，MCP 都提供了一种标准化的方式将大语言模型（LLM）与相关上下文数据连接起来。

本教程指导您设置 Milvus 的 MCP 服务器，让 AI 应用程序能够使用自然语言命令执行向量搜索、管理 Collection 和检索数据，而无需编写自定义数据库查询。

先决条件

在设置 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

支持的应用程序

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

• Claude Desktop：Anthropic 的 Claude 桌面应用程序
• Cursor：具有 MCP 支持的 AI 驱动代码编辑器，在其 Composer 功能中支持
• 其他自定义 MCP 客户端 任何实现 MCP 客户端规范的应用程序

在 Claude Desktop 中使用 MCP

1. 安装 Claude Desktop。
2. 打开 Claude 配置文件：
   • 在 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 中使用 MCP

Cursor 也通过其 Composer 中的 Agent 功能支持 MCP 工具。您可以通过两种方式将 Milvus MCP 服务器添加到 Cursor：

选项 1：使用 Cursor 设置 UI

1. 打开 Cursor Settings → Features → MCP。
2. 点击 + Add New MCP Server。
3. 填写：
   • 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：使用项目特定配置（推荐）

1. 在您的项目根目录中创建 .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"
      ]
    }
  }
}

2. 重启 Cursor 以应用配置。

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

验证集成

确保 MCP 服务器正确设置：

对于 Cursor

1. 转到 Cursor Settings → Features → MCP。
2. 确认 "Milvus" 出现在 MCP 服务器列表中。
3. 检查是否列出了 Milvus 工具（例如，milvus_list_collections、milvus_vector_search）。
4. 如果出现错误，请参阅下面的故障排除部分。

Milvus 的 MCP 服务器工具

此 MCP 服务器提供多个工具用于搜索、查询和管理 Milvus 中的向量数据。更多详细信息，请参考 mcp-server-milvus 文档。

🔍 搜索和查询工具

• milvus-text-search → 使用全文搜索搜索文档。
• milvus-vector-search → 对 Collection 执行向量相似性搜索。
• milvus-hybrid-search → 执行结合向量相似性和属性过滤的混合搜索。
• milvus-multi-vector-search → 使用多个查询向量执行向量相似性搜索。
• milvus-query → 使用过滤表达式查询 Collection。
• milvus-count → 计算 Collection 中的实体数量。

📁 Collection 管理

• milvus-list-collections → 列出数据库中的所有 Collection。
• milvus-collection-info → 获取 Collection 的详细信息。
• milvus-get-collection-stats → 获取 Collection 的统计信息。
• milvus-create-collection → 使用指定模式创建新 Collection。
• milvus-load-collection → 将 Collection 加载到内存中进行搜索和查询。
• milvus-release-collection → 从内存中释放 Collection。
• milvus-get-query-segment-info → 获取查询段的信息。
• milvus-get-collection-loading-progress → 获取 Collection 的加载进度。

📊 数据操作

• milvus-insert-data → 向 Collection 中插入数据。
• milvus-bulk-insert → 批量插入数据以获得更好的性能。
• milvus-upsert-data → 向 Collection 中进行 upsert 操作（插入或如果存在则更新）。
• milvus-delete-entities → 基于过滤表达式从 Collection 中删除实体。
• milvus-create-dynamic-field → 向现有 Collection 添加动态 Field。

⚙️ Index 管理

• milvus-create-index → 在向量 Field 上创建 Index。
• milvus-get-index-info → 获取 Collection 中 Index 的信息。

环境变量

• MILVUS_URI → Milvus 服务器 URI（可以设置而不是 --milvus-uri）。
• MILVUS_TOKEN → 可选的身份验证令牌。
• MILVUS_DB → 数据库名称（默认为 "default"）。

Development

To run the server directly:

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

Examples

Using Claude Desktop

Example 1: Listing Collections

What are the collections I have in my Milvus DB?

Claude will then use MCP to check this information on our Milvus DB.

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

> View result from milvus-list-collections from milvus (local)

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

Example 2: Searching for Documents

Find documents in my text_collection that mention "machine learning"

Claude will use the full-text search capabilities of Milvus to find relevant documents:

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]

Using Cursor

Example: Creating a Collection

In Cursor's Composer, you can ask:

Create a new collection called 'articles' in Milvus with fields for title (string), content (string), and a vector field (128 dimensions)

Cursor will use the MCP server to execute this operation:

I'll create a new collection called 'articles' with the specified fields.

> View result from milvus-create-collection from milvus (local)

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

Troubleshooting

Common Issues

Connection Errors

If you see errors like "Failed to connect to Milvus server":

1. Verify your Milvus instance is running: docker ps (if using Docker)
2. Check the URI is correct in your configuration
3. Ensure there are no firewall rules blocking the connection
4. Try using 127.0.0.1 instead of localhost in the URI

Authentication Issues

If you see authentication errors:

1. Verify your MILVUS_TOKEN is correct
2. Check if your Milvus instance requires authentication
3. Ensure you have the correct permissions for the operations you're trying to perform

Tool Not Found

If the MCP tools don't appear in Claude Desktop or Cursor:

1. Restart the application
2. Check the server logs for any errors
3. Verify the MCP server is running correctly
4. Press the refresh button in the MCP settings (for Cursor)

Getting Help

If you continue to experience issues:

1. Check the GitHub Issues for similar problems
2. Join the Zilliz Community Discord for support
3. File a new issue with detailed information about your problem

总结

通过遵循本教程，您现在拥有了一个运行中的 MCP 服务器，可以在 Milvus 中启用 AI 驱动的向量搜索。无论您使用的是 Claude Desktop 还是 Cursor，您现在都可以使用自然语言命令查询、管理和搜索您的 Milvus 数据库，而无需编写数据库代码！