Qdrant MCP
官方使用 Qdrant 向量資料庫進行語意搜尋。
你可以用 Qdrant MCP 做什麼?
- 儲存記憶 — 請助理使用
qdrant-store將資訊(可選擇加入中繼資料)儲存至 Qdrant 集合。 - 語意搜尋 — 使用自然語言
query搭配qdrant-find,擷取相關的已儲存資訊。 - 選擇集合 — 每次呼叫時指定目標
collection_name,或透過COLLECTION_NAME設定預設值。 - 自訂工具描述 — 調整
TOOL_STORE_DESCRIPTION和TOOL_FIND_DESCRIPTION,將伺服器改造成程式碼片段搜尋工具。 - 唯讀模式 — 啟用
QDRANT_READ_ONLY以停用儲存功能,僅允許擷取資訊。 - 調整結果 — 使用
QDRANT_SEARCH_LIMIT限制搜尋結果數量,並透過EMBEDDING_MODEL選擇嵌入模型。
文件
mcp-server-qdrant:Qdrant MCP 伺服器
Model Context Protocol (MCP) 是一種開放協定,可讓 LLM 應用程式與外部資料來源及工具 無縫整合。無論您是要打造 AI 驅動的 IDE、強化聊天介面,還是建立自訂 AI 工作流程,MCP 都提供標準化方式, 將 LLM 連接至所需的上下文。
此儲存庫示範如何為向量搜尋引擎 Qdrant 建立 MCP 伺服器。
概覽
官方 Model Context Protocol 伺服器,用於在 Qdrant 向量搜尋引擎中儲存及擷取記憶。 它在 Qdrant 資料庫之上提供語意記憶層。
元件
工具
qdrant-store- 在 Qdrant 資料庫中儲存資訊
- 輸入:
information(string):要儲存的資訊metadata(JSON):要儲存的選用中繼資料collection_name(string):要儲存資訊的集合名稱。若未設定預設集合名稱,此欄位為必填。 若已設定預設集合名稱,則不會啟用此欄位。
- 傳回:確認訊息
qdrant-find- 從 Qdrant 資料庫擷取相關資訊
- 輸入:
query(string):用於搜尋的查詢collection_name(string):要儲存資訊的集合名稱。若未設定預設集合名稱,此欄位為必填。 若已設定預設集合名稱,則不會啟用此欄位。
- 傳回:以個別訊息形式傳回儲存在 Qdrant 資料庫中的資訊
環境變數
透過環境變數進行設定。唯一的命令列引數是 --transport,用於選取傳輸協定。
[!NOTE] 不可同時提供
QDRANT_URL和QDRANT_LOCAL_PATH。
| 名稱 | 說明 | 預設值 |
|---|---|---|
QDRANT_URL | Qdrant 伺服器的 URL | None |
QDRANT_API_KEY | Qdrant 伺服器的 API 金鑰 | None |
COLLECTION_NAME | 要使用的預設集合名稱。 | None |
QDRANT_LOCAL_PATH | 本機 Qdrant 資料庫的路徑(QDRANT_URL 的替代方案) | None |
EMBEDDING_PROVIDER | 要使用的嵌入提供者(目前僅支援 "fastembed") | fastembed |
EMBEDDING_MODEL | 要使用的嵌入模型名稱 | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | store 工具的自訂說明 | 請參閱 settings.py 中的預設值 |
TOOL_FIND_DESCRIPTION | find 工具的自訂說明 | 請參閱 settings.py 中的預設值 |
QDRANT_SEARCH_LIMIT | 搜尋結果的最大傳回數量 | 10 |
QDRANT_READ_ONLY | 啟用唯讀模式(停用 qdrant-store 工具) | false |
FastMCP 環境變數
由於 mcp-server-qdrant 以 FastMCP 為基礎,因此也支援所有 FastMCP 環境變數。以下列出其中
最重要的變數:
| 環境變數 | 說明 | 預設值 |
|---|---|---|
FASTMCP_LOG_LEVEL | 設定記錄層級(DEBUG、INFO、WARNING、ERROR、CRITICAL) | INFO |
FASTMCP_DEBUG | 啟用偵錯模式 | false |
FASTMCP_HOST | 伺服器要繫結的主機位址(SSE 和 HTTP 傳輸) | 127.0.0.1 |
FASTMCP_PORT | 伺服器執行的連接埠(SSE 和 HTTP 傳輸) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | 隱藏傳送給用戶端的工具錯誤訊息中的例外詳細資訊 | false |
[!NOTE] 在 0.9.0 版之前,這些設定使用
FASTMCP_SERVER_前綴,例如FASTMCP_SERVER_HOST。 舊的FASTMCP_SERVER_HOST、FASTMCP_SERVER_PORT和FASTMCP_SERVER_DEBUG名稱仍可使用,但已棄用, 並將在未來版本中移除。若同時設定新舊名稱,將以新名稱為準。
安裝
使用 uvx
使用 uvx 時,無需特別安裝即可直接執行 mcp-server-qdrant。
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
傳輸協定
伺服器支援多種傳輸協定,可使用 --transport 旗標指定:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
支援的傳輸協定:
stdio(預設):標準輸入/輸出傳輸,可能僅適用於本機 MCP 用戶端sse:Server-Sent Events 傳輸,非常適合遠端用戶端streamable-http:Streamable HTTP 傳輸,非常適合遠端用戶端,且比 SSE 新
若未指定,預設傳輸協定為 stdio。
使用 SSE 傳輸時,伺服器會在指定的連接埠上監聽並等待連線。預設
連接埠為 8000,但可使用 FASTMCP_PORT 環境變數變更。
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
使用 Docker
提供 Dockerfile,可用於建置及執行 MCP 伺服器:
# Build the container
docker build -t mcp-server-qdrant .
# Run the container
docker run -p 8000:8000 \
-e FASTMCP_HOST="0.0.0.0" \
-e QDRANT_URL="http://your-qdrant-server:6333" \
-e QDRANT_API_KEY="your-api-key" \
-e COLLECTION_NAME="your-collection" \
mcp-server-qdrant
[!TIP] 請注意,我們將
FASTMCP_HOST="0.0.0.0"設為讓伺服器監聽所有網路介面。使用 Docker 容器執行伺服器時, 這是必要設定。
透過 Smithery 安裝
若要透過 Smithery 自動安裝 Claude Desktop 的 Qdrant MCP Server:
npx @smithery/cli install mcp-server-qdrant --client claude
手動設定 Claude Desktop
若要在 Claude Desktop 應用程式中使用此伺服器,請將以下設定新增至
claude_desktop_config.json 的 "mcpServers" 區段:
{
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
"QDRANT_API_KEY": "your_api_key",
"COLLECTION_NAME": "your-collection-name",
"EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
}
}
}
本機 Qdrant 模式:
{
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
"COLLECTION_NAME": "your-collection-name",
"EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
}
}
}
如果指定名稱的集合不存在,此 MCP 伺服器會自動建立該集合。
伺服器預設會使用 sentence-transformers/all-MiniLM-L6-v2 嵌入模型來編碼記憶。
目前僅支援 FastEmbed 模型。
支援其他工具
此 MCP 伺服器可搭配任何相容 MCP 的用戶端使用。例如,您可以搭配 Cursor 和 VS Code 使用,這些工具內建 Model Context Protocol 支援。
搭配 Cursor/Windsurf 使用
您可以自訂工具說明,將此 MCP 伺服器設定為 Cursor 或 Windsurf 的程式碼搜尋工具:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport
接著,您可以在 Cursor/Windsurf 設定中,透過 SSE 傳輸協定指向正在執行的伺服器,以設定 MCP 伺服器。如何將 MCP 伺服器新增至 Cursor 的說明,請參閱 Cursor 文件。如果您在本機 執行 Cursor/Windsurf,可以使用以下 URL:
http://localhost:8000/sse
[!TIP] 我們建議使用 SSE 傳輸作為 Cursor/Windsurf 連接 MCP 伺服器的首選方式,因為它支援遠端 連線。這讓您能輕鬆與團隊共用伺服器,或在雲端環境中使用。
此設定會將 Qdrant MCP 伺服器轉換為專用的程式碼搜尋工具,可用於:
- 儲存程式碼片段、文件和實作細節
- 根據語意搜尋擷取相關程式碼範例
- 協助開發人員尋找特定實作或使用模式
您可以將程式碼片段的自然語言描述(放在 information 參數中)
與實際程式碼(放在 metadata.code 屬性中)一併儲存,以填入資料庫;之後再使用描述所需內容的自然語言查詢
來搜尋。
[!NOTE] 上述工具說明僅為範例,可能需要依您的特定使用情境進行自訂。請考慮調整說明,使其更符合團隊的工作流程 以及您想要儲存和擷取的程式碼片段類型。
如果您已成功安裝 mcp-server-qdrant,但仍無法讓它與 Cursor 搭配運作,請考慮建立 Cursor 規則,確保代理程式產生新的程式碼片段時一律使用 MCP 工具。 您可以限制規則僅適用於特定檔案類型,避免在文件或其他類型的內容中使用
MCP 伺服器。
搭配 Claude Code 使用
將 Claude Code 連接至此 MCP 伺服器,即可透過語意搜尋強化其功能,搜尋您現有的程式碼庫。
設定 mcp-server-qdrant
-
將 MCP 伺服器新增至 Claude Code:
# Add mcp-server-qdrant configured for code search claude mcp add code-search \ -e QDRANT_URL="http://localhost:6333" \ -e COLLECTION_NAME="code-repository" \ -e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \ -e TOOL_STORE_DESCRIPTION="Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property." \ -e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \ -- uvx mcp-server-qdrant -
確認伺服器已新增:
claude mcp list
在 Claude Code 中使用語意程式碼搜尋
在 TOOL_STORE_DESCRIPTION 和 TOOL_FIND_DESCRIPTION 中指定的工具說明,會引導 Claude Code 使用
MCP 伺服器。上述說明僅為範例,可能需要依您的特定使用情境進行自訂。不過,Claude Code 應已能夠:
- 使用
qdrant-store工具,搭配說明儲存程式碼片段。 - 使用
qdrant-find工具,以自然語言搜尋相關程式碼片段。
在開發模式中執行 MCP 伺服器
您可以使用 mcp dev 命令以開發模式執行 MCP 伺服器。這會啟動伺服器,並在瀏覽器中開啟 MCP
檢查器。
COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py
搭配 VS Code 使用
若要一鍵安裝,請點選下方其中一個安裝按鈕:
手動安裝
將以下 JSON 區塊新增至 VS Code 的使用者設定 (JSON) 檔案。您可以按下 Ctrl + Shift + P,然後輸入 Preferences: Open User Settings (JSON)。
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
}
或者,如果您偏好使用 Docker,請改為新增此設定:
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "docker",
"args": [
"run",
"-p", "8000:8000",
"-i",
"--rm",
"-e", "QDRANT_URL",
"-e", "QDRANT_API_KEY",
"-e", "COLLECTION_NAME",
"mcp-server-qdrant"
],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
}
您也可以在工作區中建立 .vscode/mcp.json 檔案,並加入以下內容:
{
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
若要使用 Docker 設定工作區,請在 .vscode/mcp.json 中使用以下設定:
{
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "docker",
"args": [
"run",
"-p", "8000:8000",
"-i",
"--rm",
"-e", "QDRANT_URL",
"-e", "QDRANT_API_KEY",
"-e", "COLLECTION_NAME",
"mcp-server-qdrant"
],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
貢獻
如果您對如何改進 mcp-server-qdrant 有任何建議,或想回報錯誤,請建立 issue! 我們非常歡迎任何形式的貢獻。
在本機測試 mcp-server-qdrant
MCP 檢查器 是用於測試及偵錯 MCP 伺服器的開發者工具。它會同時執行用戶端 UI(預設連接埠 5173)和 MCP Proxy 伺服器(預設連接埠 3000)。在 瀏覽器中開啟用戶端 UI,即可使用檢查器。
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
啟動後,請在瀏覽器中開啟 http://localhost:5173 以使用檢查器介面。
授權條款
此 MCP 伺服器採用 Apache License 2.0 授權。這表示您可以自由使用、修改及散布 本軟體,但須遵守 Apache License 2.0 的條款與條件。詳情請參閱專案儲存庫中的 LICENSE 檔案。