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

模型上下文协议（MCP）是一种开放协议，可实现 LLM 应用程序与外部数据源和工具之间的无缝集成。无论您是在构建由 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都提供了一种标准化的方式，将 LLM 与它们所需的上下文连接起来。

此仓库是展示如何为 Qdrant（一个向量搜索引擎）创建 MCP 服务器的示例。

概述

一个官方的模型上下文协议服务器，用于在 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：服务器发送事件（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 中，您可以在设置中配置 MCP 服务器，通过指向使用 SSE 传输协议运行的此服务器。有关如何向 Cursor 添加 MCP 服务器的说明，请参阅 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 配合使用

您可以通过将此 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 检查器是用于测试和调试 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 文件。