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 伺服器

smithery badge

Model Context Protocol (MCP) 是一種開放協定,可讓 LLM 應用程式與外部資料來源及工具 無縫整合。無論您是要打造 AI 驅動的 IDE、強化聊天介面,還是建立自訂 AI 工作流程,MCP 都提供標準化方式, 將 LLM 連接至所需的上下文。

此儲存庫示範如何為向量搜尋引擎 Qdrant 建立 MCP 伺服器。

概覽

官方 Model Context Protocol 伺服器,用於在 Qdrant 向量搜尋引擎中儲存及擷取記憶。 它在 Qdrant 資料庫之上提供語意記憶層。

元件

工具

  1. qdrant-store
    • 在 Qdrant 資料庫中儲存資訊
    • 輸入:
      • information (string):要儲存的資訊
      • metadata (JSON):要儲存的選用中繼資料
      • collection_name (string):要儲存資訊的集合名稱。若未設定預設集合名稱,此欄位為必填。 若已設定預設集合名稱,則不會啟用此欄位。
    • 傳回:確認訊息
  2. qdrant-find
    • 從 Qdrant 資料庫擷取相關資訊
    • 輸入:
      • query (string):用於搜尋的查詢
      • collection_name (string):要儲存資訊的集合名稱。若未設定預設集合名稱,此欄位為必填。 若已設定預設集合名稱,則不會啟用此欄位。
    • 傳回:以個別訊息形式傳回儲存在 Qdrant 資料庫中的資訊

環境變數

透過環境變數進行設定。唯一的命令列引數是 --transport,用於選取傳輸協定。

[!NOTE] 不可同時提供 QDRANT_URL 和 QDRANT_LOCAL_PATH。

名稱說明預設值
QDRANT_URLQdrant 伺服器的 URLNone
QDRANT_API_KEYQdrant 伺服器的 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_DESCRIPTIONstore 工具的自訂說明請參閱 settings.py 中的預設值
TOOL_FIND_DESCRIPTIONfind 工具的自訂說明請參閱 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 伺服器轉換為專用的程式碼搜尋工具,可用於:

  1. 儲存程式碼片段、文件和實作細節
  2. 根據語意搜尋擷取相關程式碼範例
  3. 協助開發人員尋找特定實作或使用模式

您可以將程式碼片段的自然語言描述(放在 information 參數中) 與實際程式碼(放在 metadata.code 屬性中)一併儲存,以填入資料庫;之後再使用描述所需內容的自然語言查詢 來搜尋。

[!NOTE] 上述工具說明僅為範例,可能需要依您的特定使用情境進行自訂。請考慮調整說明,使其更符合團隊的工作流程 以及您想要儲存和擷取的程式碼片段類型。

如果您已成功安裝 mcp-server-qdrant,但仍無法讓它與 Cursor 搭配運作,請考慮建立 Cursor 規則,確保代理程式產生新的程式碼片段時一律使用 MCP 工具。 您可以限制規則僅適用於特定檔案類型,避免在文件或其他類型的內容中使用 MCP 伺服器。

搭配 Claude Code 使用

將 Claude Code 連接至此 MCP 伺服器,即可透過語意搜尋強化其功能,搜尋您現有的程式碼庫。

設定 mcp-server-qdrant

  1. 將 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
    
  2. 確認伺服器已新增:

    claude mcp list
    

在 Claude Code 中使用語意程式碼搜尋

在 TOOL_STORE_DESCRIPTION 和 TOOL_FIND_DESCRIPTION 中指定的工具說明,會引導 Claude Code 使用 MCP 伺服器。上述說明僅為範例,可能需要依您的特定使用情境進行自訂。不過,Claude Code 應已能夠:

  1. 使用 qdrant-store 工具,搭配說明儲存程式碼片段。
  2. 使用 qdrant-find 工具,以自然語言搜尋相關程式碼片段。

在開發模式中執行 MCP 伺服器

您可以使用 mcp dev 命令以開發模式執行 MCP 伺服器。這會啟動伺服器,並在瀏覽器中開啟 MCP 檢查器。

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

搭配 VS Code 使用

若要一鍵安裝,請點選下方其中一個安裝按鈕:

Install with UVX in VS Code Install with UVX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

手動安裝

將以下 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 檔案。

隱私權與支援