Qdrant MCP Server

官方

使用 Qdrant 向量資料庫進行語意搜尋。

GitHub
1.4k

文件

mcp-server-qdrant：一個 Qdrant MCP 伺服器

smithery badge

模型上下文協定 (Model Context Protocol, MCP) 是一個開放協定，能讓 LLM 應用程式與外部資料來源和工具之間實現無縫整合。無論您是在建置 AI 驅動的 IDE、增強聊天介面，或是建立自訂的 AI 工作流程，MCP 都提供了一種標準化的方式 將 LLM 與它們所需的上下文連接起來。

此儲存庫是一個範例，展示如何為向量搜尋引擎 Qdrant 建立 MCP 伺服器。

概覽

一個官方的模型上下文協定伺服器，用於在 Qdrant 向量搜尋引擎中保存和檢索記憶。 它作為 Qdrant 資料庫之上的語意記憶層。

元件

工具

  1. qdrant-store
    • 將一些資訊儲存到 Qdrant 資料庫中
    • 輸入：
      • information (字串)：要儲存的資訊
      • metadata (JSON)：要儲存的可選中繼資料
      • collection_name (字串)：用於儲存資訊的集合名稱。如果沒有預設集合名稱，則此欄位為必填。 如果有預設集合名稱，則不會啟用此欄位。
    • 回傳：確認訊息
  2. qdrant-find
    • 從 Qdrant 資料庫中檢索相關資訊
    • 輸入：
      • query (字串)：用於搜尋的查詢
      • collection_name (字串)：用於儲存資訊的集合名稱。如果沒有預設集合名稱，則此欄位為必填。 如果有預設集合名稱，則不會啟用此欄位。
    • 回傳：以獨立訊息形式儲存在 Qdrant 資料庫中的資訊

環境變數

設定是透過環境變數完成的。唯一的命令列參數是 --transport，用於選擇傳輸協定。

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

名稱說明預設值
QDRANT_URLQdrant 伺服器的 URL無
QDRANT_API_KEYQdrant 伺服器的 API 金鑰無
COLLECTION_NAME要使用的預設集合名稱。無
QDRANT_LOCAL_PATH本地 Qdrant 資料庫的路徑（QDRANT_URL 的替代方案）無
EMBEDDING_PROVIDER要使用的嵌入提供者（目前僅支援 "fastembed"）fastembed
EMBEDDING_MODEL要使用的嵌入模型名稱sentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTION儲存工具的自訂描述請參閱 settings.py 中的預設值
TOOL_FIND_DESCRIPTION尋找工具的自訂描述請參閱 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_SERVER_DEBUG啟用除錯模式false
FASTMCP_SERVER_HOST伺服器綁定的主機位址127.0.0.1
FASTMCP_SERVER_PORT伺服器執行的連接埠8000
FASTMCP_SERVER_ON_DUPLICATE_RESOURCES重複資源的行為 (warn, error, replace, ignore)warn
FASTMCP_SERVER_ON_DUPLICATE_TOOLS重複工具的行為 (warn, error, replace, ignore)warn
FASTMCP_SERVER_ON_DUPLICATE_PROMPTS重複提示的行為 (warn, error, replace, ignore)warn
FASTMCP_SERVER_DEPENDENCIES要在伺服器環境中安裝的相依性清單[]

[!NOTE] 伺服器專用設定使用 FASTMCP_SERVER_ 前綴。這在未來的版本中可能會變更。

安裝

使用 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：伺服器傳送事件傳輸，非常適合遠端客戶端
  • streamable-http：可串流的 HTTP 傳輸，非常適合遠端客戶端，比 SSE 更新

如果未指定，預設傳輸為 stdio。

使用 SSE 傳輸時，伺服器將監聽指定的連接埠並等待傳入的連線。預設 連接埠為 8000，但可以使用 FASTMCP_SERVER_PORT 環境變數進行變更。

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_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_SERVER_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_SERVER_HOST="0.0.0.0" 是為了讓伺服器監聽所有網路介面。這在 Docker 容器中執行伺服器時是必要的。

透過 Smithery 安裝

要透過 Smithery 為 Claude Desktop 自動安裝 Qdrant MCP 伺服器：

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 搭配使用，它們提供了對模型上下文協定的內建支援。

與 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 的說明，可以在 https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-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 代理伺服器（預設連接埠 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 檔案。