Qdrant

官方

在 Qdrant 向量搜尋引擎之上實作語意記憶層

GitHub

1.5k

你可以用 Qdrant MCP 做什麼？

儲存記憶 — 要求您的助理使用 qdrant-store 儲存資訊，可選擇性地包含中繼資料並指定特定集合。
語意搜尋 — 使用 qdrant-find 透過自然語言查詢檢索相關的已儲存資訊，結果數量由 QDRANT_SEARCH_LIMIT 限制。
程式碼片段管理 — 設定工具描述以儲存含中繼資料的程式碼，並透過語意搜尋檢索，以便在 Cursor 或 Claude Code 中重複使用。
唯讀模式 — 啟用 QDRANT_READ_ONLY 以停用 qdrant-store，僅允許搜尋操作。

文件

mcp-server-qdrant: A Qdrant MCP server

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	無
`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`	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_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 中，您可以透過指向使用 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 伺服器轉換為專門的程式碼搜尋工具，可以：

儲存程式碼片段、文件和實作細節
基於語意搜尋檢索相關的程式碼範例
幫助開發人員找到特定的實作或使用模式

您可以透過在 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 inspector。

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 以使用 inspector。

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

啟動後，請在瀏覽器中開啟 http://localhost:5173 以存取 inspector 介面。

授權

此 MCP 伺服器採用 Apache License 2.0 授權。這表示您可以自由使用、修改和散布此軟體，但須遵守 Apache License 2.0 的條款與條件。如需更多詳細資訊，請參閱專案儲存庫中的 LICENSE 檔案。