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

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

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

概览

这是一个基本的模型上下文协议服务器，用于在 Qdrant 向量搜索引擎中存储和检索记忆。
它作为 Qdrant 数据库之上的语义记忆层。

组件

工具

1. qdrant-store
   • 在 Qdrant 数据库中存储一些信息
   • 输入：
     • information (字符串): 要存储的信息
     • metadata (JSON): 可选的元数据
   • 返回: 确认消息
2. qdrant-find
   • 从 Qdrant 数据库中检索相关信息
   • 输入：
     • query (字符串): 用于搜索的查询
   • 返回: 存储在 Qdrant 数据库中的信息，以单独的消息形式返回

环境变量

服务器的配置是通过环境变量完成的：

注意：你不能同时提供 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 服务器：

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
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 服务器：

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 一起使用，后者提供了对 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 服务器。有关如何向 Cursor 添加 MCP 服务器的说明，请参阅 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 服务器处理文档或其他类型的内容。

贡献

如果您有关于如何改进 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许可证2.0版授权。这意味着您可以在遵守Apache许可证2.0版的条款和条件的前提下自由使用、修改和分发该软件。更多详情，请参阅项目仓库中的LICENSE文件。