Milvus的MCP服务器
模型上下文协议（MCP）是一种开放协议，可实现LLM应用程序与外部数据源和工具之间的无缝集成。无论您是在构建基于AI的IDE、增强聊天界面，还是创建自定义AI工作流程，MCP都提供了一种标准化的方式将LLM与所需的上下文连接起来。
此存储库包含一个MCP服务器，可访问 米尔维斯 矢量数据库功能。
先决条件
在使用此MCP服务器之前，请确保您已：
用法
建议使用此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/ 目录中设置环境变量，并使用以下命令运行服务器：
uv run src/mcp_server_milvus/server.py重要提示：.env文件的优先级将高于命令行参数。
运行模式
服务器支持两种运行模式： 标准 （默认）和 上海证券交易所 （服务器发送的事件）。
标准模式（默认）
- 描述：通过标准输入/输出与客户沟通。如果未指定模式，则这是默认模式。
- 用途：
uv run src/mcp_server_milvus/server.py --milvus-uri http://localhost:19530SSE模式
- 描述：使用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 🚀然后，您可以访问MCP检查器 http://127.0.0.1:6274 用于测试。
流式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应用程序一起使用：
- 克劳德桌面版：克劳德的Anthropic桌面应用程序
- 光标：支持MCP的AI驱动代码编辑器
- 自定义MCP客户端：任何实现MCP客户端规范的应用程序
使用Claude Desktop
不同模式的配置
SSE模式配置
按照以下步骤将Claude Desktop配置为SSE模式：
- 从以下位置安装Claude Desktophttps://claude.ai/download.
- 打开您的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": []
}
}
}流式HTTP模式配置
{
"mcpServers": {
"milvus-streamable-http": {
"url": "http://your_host:port/mcp",
"disabled": false,
"autoApprove": []
}
}
}- 重新启动Claude Desktop以应用更改。
标准模式配置
对于stdio模式，请执行以下步骤：
- 从以下位置安装Claude Desktophttps://claude.ai/download.
- 打开您的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还支持MCP 工具。您可以按照以下步骤将Milvus MCP服务器与Cursor集成：
集成步骤
- 打开
Cursor Settings>MCP - 点击
Add new global MCP server - 点击后，它会自动将您重定向到
mcp.json文件，如果不存在，将创建该文件
配置 mcp.json 文件
对于标准模式：
覆盖 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": []
}
}
}对于流式HTTP模式：
- 启动服务：
uv run src/mcp_server_milvus/server.py --streamable-http --milvus-uri http://your_host --port port- 更新
mcp.json:
{
"mcpServers": {
"milvus-streamable-http": {
"url": "http://your_host:port/mcp",
"disabled": false,
"autoApprove": []
}
}
}完成集成
完成上述步骤后，重新启动Cursor或重新加载窗口以确保配置生效。
验证集成
要验证Cursor是否已成功与Milvus MCP服务器集成：
- 打开
Cursor Settings>MCP - 检查列表中是否出现“milvus”、“milvus-sse”或“milvus-可流式传输http”（取决于您选择的模式）
- 确认列出了相关工具（例如milvus_list_collections、milvus_vector_search等）
- 如果服务器已启用但显示错误，请检查下面的故障排除部分
可用工具
服务器提供以下工具：
搜索和查询操作
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：范围搜索的可选下限（默认值：无） - range_filter：范围搜索的可选上限（默认值：无）
milvus_hybrid_search：对集合执行混合搜索
- 参数： - collection_name：要搜索的集合名称 - query_text：用于搜索的文本查询 - text_field：文本搜索的字段名 - vector：文本查询的向量 - vector_field：矢量搜索的字段名 - limit：要返回的最大结果数（默认值：5） - output_fields：要包含在结果中的字段 - filter_expr：筛选器表达式 - sparse_radius：稀疏范围搜索的可选下限（默认值：无） - sparse_range_filter：稀疏范围搜索的可选上限（默认值：无） - dense_radius：密集范围搜索的可选下限（默认值：无） - dense_range_filter：密集范围搜索的可选上限（默认值：无）
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：范围搜索的可选下限（默认值：无） - range_filter：范围搜索的可选上限（默认值：无）
milvus_query：使用筛选表达式查询集合
- 参数： - collection_name：要查询的集合名称 - filter_expr：筛选表达式（例如“年龄>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：数据库名称（默认为“默认”）
发展
要直接运行服务器，请执行以下操作：
uv run server.py --milvus-uri http://localhost:19530示例
使用克劳德桌面
示例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中，您可以问：
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]故障排除
常见问题
连接错误
如果您看到诸如“连接到Milvus服务器失败”之类的错误：
- 验证您的Milvus实例是否正在运行：
docker ps（如果使用Docker） - 检查配置中的URI是否正确
- 确保没有防火墙规则阻止连接
- 尝试使用
127.0.0.1而不是localhost在URI中
身份验证问题
如果您看到身份验证错误：
- 验证您的
MILVUS_TOKEN是正确的 - 检查您的Milvus实例是否需要身份验证
- 确保您对尝试执行的操作具有正确的权限
未找到工具
如果MCP工具未出现在克劳德桌面或光标中：
- 重新启动应用程序
- 检查服务器日志是否有任何错误
- 验证MCP服务器是否正常运行
- 按下MCP设置中的刷新按钮（光标）
获取帮助
如果您继续遇到问题：
- 检查 对于类似的问题
- 加入 Milvus社区不和 支持
- 提交一个新问题，其中包含有关您问题的详细信息