mcp-server-qdrant：一个 Qdrant MCP 服务器

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

此存储库演示了如何为 Qdrant（一个向量搜索引擎）创建 MCP 服务器。

<a href="https://glama.ai/mcp/servers/9ejy5scw5i"><img width="380" height="200" src="https://glama.ai/mcp/servers/9ejy5scw5i/badge" alt="mcp-server-qdrant MCP server" /></a>

概述

一个官方的模型上下文协议服务器，用于在 Qdrant 向量搜索引擎中保存和检索记忆。它充当 Qdrant 数据库之上的语义记忆层。

组件

工具

1. qdrant-store
   • 将一些信息存储在 Qdrant 数据库中
   • 输入：
     • information (字符串)：要存储的信息
     • metadata (JSON)：要存储的可选元数据
     • collection_name (字符串)：用于存储信息的集合的名称。如果没有默认集合名称，则此字段是必需的。 如果存在默认集合名称，则此字段不启用。
   • 返回：确认消息
2. qdrant-find
   • 从 Qdrant 数据库中检索相关信息
   • 输入：
     • query (字符串)：用于搜索的查询
     • collection_name (字符串)：用于存储信息的集合的名称。如果没有默认集合名称，则此字段是必需的。 如果存在默认集合名称，则此字段不启用。
   • 返回：存储在 Qdrant 数据库中的信息，作为单独的消息

环境变量

服务器的配置使用环境变量完成：

名称	描述	默认值
QDRANT_URL	Qdrant 服务器的 URL	None
QDRANT_API_KEY	Qdrant 服务器的 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_DESCRIPTION	存储工具的自定义描述	请参阅 settings.py 中的默认值
TOOL_FIND_DESCRIPTION	查找工具的自定义描述	请参阅 settings.py 中的默认值

注意：您不能同时提供 QDRANT_URL 和 QDRANT_LOCAL_PATH。

[!IMPORTANT] 不再支持命令行参数！请使用环境变量进行所有配置。

安装

使用 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：服务器发送事件传输，非常适合远程客户端

如果未指定，则默认传输为 stdio。

使用 Docker

Dockerfile 可用于构建和运行 MCP 服务器：

# 构建容器
docker build -t mcp-server-qdrant .

# 运行容器
docker run -p 8000:8000 \
  -e QDRANT_URL="http://your-qdrant-server:6333" \
  -e QDRANT_API_KEY="your-api-key" \
  -e COLLECTION_NAME="your-collection" \
  mcp-server-qdrant

通过 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 一起使用，后者提供对模型上下文协议的内置支持。

与 Cursor/Windsurf 一起使用

您可以通过自定义工具描述来配置此 MCP 服务器，使其用作 Cursor 或 Windsurf 的代码搜索工具：

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="存储可重用的代码片段以供以后检索。\
'information' 参数应包含代码作用的自然语言描述，\
而实际代码应包含在 'metadata' 参数中作为 'code' 属性。\
'metadata' 的值是一个以字符串为键的 Python 字典。\
每当您生成一些代码片段时，请使用此方法。" \
TOOL_FIND_DESCRIPTION="根据自然语言描述搜索相关的代码片段。\
'query' 参数应描述您要查找的内容，\
该工具将返回最相关的代码片段。\
当您需要查找现有代码片段以供重用或参考时，请使用此方法。" \
uvx mcp-server-qdrant --transport sse # 启用 SSE 传输

在 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：

   # 添加为代码搜索配置的 mcp-server-qdrant
   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="存储带有描述的代码片段。'information' 参数应包含代码作用的自然语言描述，而实际代码应包含在 'metadata' 参数中作为 'code' 属性。" \
   -e TOOL_FIND_DESCRIPTION="使用自然语言搜索相关的代码片段。'query' 参数应描述您要查找的功能。" \
   -- 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 mcp dev src/mcp_server_qdrant/server.py

贡献

如果您对如何改进 mcp-server-qdrant 有任何建议，或者想报告错误，请打开一个 issue！我们欢迎所有贡献。

在本地测试 mcp-server-qdrant

MCP 检查器 是一个用于测试和调试 MCP 服务器的开发工具。它运行客户端 UI（默认端口 5173）和 MCP 代理服务器（默认端口 3000）。在您的浏览器中打开客户端 UI 以使用检查器。

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

启动后，在您的浏览器中打开 http://localhost:5173 以访问检查器界面。

许可证

此 MCP 服务器在 Apache License 2.0 下获得许可。这意味着您可以自由使用、修改和分发该软件，但须遵守 Apache License 2.0 的条款和条件。有关更多详细信息，请参阅项目存储库中的 LICENSE 文件。