Milvus MCP Server

適用於 Milvus 的 MCP 伺服器

模型上下文協定 (Model Context Protocol, 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 連接，適用於基於網頁的應用程式。
使用方式：
```
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：

從 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": []
    }
  }
}

可串流的 HTTP 模式設定

{
  "mcpServers": {
    "milvus-streamable-http": {
      "url": "http://your_host:port/mcp",
      "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 Settings > MCP
點擊 Add new global MCP server
點擊後，它將自動將您重新導向至 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": []
      }
    }
}

對於可串流的 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-streamable-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：篩選表達式（例如 '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 DB 上檢查此資訊。

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]

疑難排解

常見問題

連線錯誤

如果您看到類似「無法連線到 Milvus 伺服器」的錯誤：

確認您的 Milvus 執行個體正在運行：docker ps（若使用 Docker）
檢查設定中的 URI 是否正確
確保沒有防火牆規則阻擋連線
嘗試在 URI 中使用 127.0.0.1 而非 localhost

驗證問題

若您看到驗證錯誤：

確認您的 MILVUS_TOKEN 正確無誤
檢查您的 Milvus 執行個體是否需要驗證
確保您具備執行相關操作的正確權限

找不到工具

若 MCP 工具未出現在 Claude Desktop 或 Cursor 中：

重新啟動應用程式
檢查伺服器記錄檔是否有任何錯誤
確認 MCP 伺服器正常運行
按下 MCP 設定中的重新整理按鈕（針對 Cursor）

取得協助

若問題持續存在：

查看 GitHub Issues 是否有類似問題
加入 Milvus 社群 Discord 尋求支援
提交新的 issue，並附上問題的詳細資訊

文件