Qdrant MCP

官方

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

GitHub

1.5k

試用此 MCP贊助

你可以用 Qdrant MCP 做什麼？

使用 Qdrant 作为 AI 助手的语义记忆层，让它能够按含义而非精确关键词来存储和检索信息。

存储语义记忆 — 让您的助手通过 qdrant-store 将信息（可附带元数据）保存到 Qdrant，以供后续检索。
检索相关记忆 — 使用 qdrant-find 以自然语言查询来搜索已存储的信息，并获取匹配结果。
构建代码片段库 — 存储带描述的代码片段，并按语义进行检索，如 Cursor 和 Claude Code 配置中所示。
指定目标集合 — 通过 collection_name 在指定集合中存储或搜索，或依赖 COLLECTION_NAME 设置的默认集合。

文件

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（字串）：要儲存的資訊
  - metadata（JSON）：要儲存的可選中繼資料
  - collection_name（字串）：要儲存資訊的集合名稱。如果沒有預設集合名稱，則此欄位為必填。如果有預設集合名稱，則此欄位不會啟用。
- 回傳：確認訊息
qdrant-find
- 從 Qdrant 資料庫檢索相關資訊
- 輸入：
  - query（字串）：用於搜尋的查詢
  - collection_name（字串）：要儲存資訊的集合名稱。如果沒有預設集合名稱，則此欄位為必填。如果有預設集合名稱，則此欄位不會啟用。
- 回傳：以獨立訊息形式儲存在 Qdrant 資料庫中的資訊

環境變數

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

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

名稱	說明	預設值
`QDRANT_URL`	Qdrant 伺服器的 URL	無
`QDRANT_API_KEY`	Qdrant 伺服器的 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：Server-Sent Events 傳輸，非常適合遠端用戶端
streamable-http：Streamable 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 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 中，您可以接著在設定中設定 MCP 伺服器，方法是使用 SSE 傳輸協定指向此執行中的伺服器。有關如何將 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 rules，以便在代理程式產生新的程式碼片段時始終使用 MCP 工具。 您可以將規則限制為僅對某些檔案類型生效，以避免將 MCP 伺服器用於文件或其他類型的內容。

與 Claude Code 搭配使用

您可以透過將此 MCP 伺服器連接到 Claude Code 來增強其功能，從而對您現有的程式碼庫進行語意搜尋。

設定 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 inspector 是一個用於測試和除錯 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 檔案。