基于Qdrant向量搜索引擎构建的MCP服务

综合介绍

mcp-server-qdrant 是一个基于 Qdrant 向量搜索引擎构建的 Model Context Protocol (MCP) 服务器。它主要用来帮助 AI 系统存储和检索记忆，特别适合需要语义搜索的场景。这个工具通过将信息转化为向量，实现高效的语义记忆管理。它支持多种客户端，比如 Claude Desktop 和 Cursor，能让开发者或用户轻松保存和查找信息。无论是个人知识管理还是团队代码搜索，mcp-server-qdrant 都能提供简单易用的解决方案。它使用 FastEmbed 模型生成嵌入，默认采用 sentence-transformers/all-MiniLM-L6-v2，并且完全开源，基于 Apache 2.0 许可，任何人都可以自由使用或修改。

功能列表

• 存储信息: 将文本信息和元数据保存到 Qdrant 数据库，支持自然语言描述和结构化数据。
• 语义检索: 根据查询内容，快速找到数据库中最相关的信息或代码片段。
• 支持多种客户端: 可与 Claude Desktop、Cursor 等 MCP 兼容工具无缝对接。
• 自定义工具描述: 允许用户调整存储和查找功能的描述，适配不同场景如代码搜索或知识管理。
• 本地与远程模式: 支持本地运行 Qdrant 或连接远程服务器，灵活性强。
• 嵌入模型支持: 使用 FastEmbed 技术，默认提供高效的嵌入生成。

使用帮助

安装流程

mcp-server-qdrant 的安装非常简单，主要有两种方式：使用 uvx 直接运行，或通过 Smithery 自动安装到 Claude Desktop。以下是详细步骤：

方法 1：使用 uvx 安装并运行

1. 准备环境: 确保你的电脑已安装 Python 3.10 或以上版本，并安装了 uvx（一个轻量级的 Python 包管理工具）。如果没有 uvx，可以用以下命令安装：

pip install uv

2. 设置环境变量: 在终端中输入以下命令，配置 Qdrant 服务器地址和集合名称。

QDRANT_URL="http://localhost:6333" COLLECTION_NAME="my-collection" uvx mcp-server-qdrant

• QDRANT_URL: Qdrant 服务器的地址。如果本地运行 Qdrant，可以保持默认值。
• COLLECTION_NAME: 你想使用的集合名称，比如 "my-collection"。
• 如果需要 API 密钥，添加 QDRANT_API_KEY="你的密钥"。

3. 运行服务器: 执行命令后，服务器会启动，默认使用 stdio 传输协议。如果需要远程访问，可以加 --transport sse 参数：

QDRANT_URL="http://localhost:6333" COLLECTION_NAME="my-collection" uvx mcp-server-qdrant --transport sse

方法 2：通过 Smithery 安装到 Claude Desktop

1. 安装 Smithery: 在终端运行以下命令，确保有 Node.js 环境：

npx @smithery/cli install mcp-server-qdrant --client claude

2. 配置 Claude Desktop: 编辑 claude_desktop_config.json 文件，在 "mcpServers" 部分添加以下内容：

{
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "http://localhost:6333",
"QDRANT_API_KEY": "你的密钥",
"COLLECTION_NAME": "你的集合名称"
}
}
}

3. 启动 Claude Desktop: 保存配置后，启动 Claude Desktop，服务器会自动运行。

本地模式配置

如果不想依赖远程 Qdrant 服务器，可以用本地模式：

1. 在配置中替换 QDRANT_URL 为 QDRANT_LOCAL_PATH，指定本地数据库路径：

   {
   "qdrant": {
   "command": "uvx",
   "args": ["mcp-server-qdrant"],
   "env": {
   "QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
   "COLLECTION_NAME": "my-collection"
   }
   }
   }
   

2. 运行后，Qdrant 会以本地模式启动，所有数据保存在指定路径。

主要功能操作

功能 1：存储信息 (qdrant-store)

• 用途: 把信息保存到 Qdrant 数据库，比如文本、代码片段或笔记。
• 操作步骤:
  1. 准备要存储的内容，比如一段描述性文字（information）和可选的元数据（metadata）。
     • 示例：information="这是一个计算器函数的描述"，metadata={"code": "def calc(x): return x + 1"}
  2. 如果用 Claude Desktop，打开客户端，输入类似命令：

     qdrant-store information="这是一个计算器函数的描述" metadata={"code": "def calc(x): return x + 1"}
     

  3. 服务器会返回确认消息，表示存储成功。
• 注意: 元数据是可选的，可以用来存额外信息，比如代码或标签。

功能 2：检索信息 (qdrant-find)

• 用途: 根据自然语言查询，找到数据库中最相关的内容。
• 操作步骤:
  1. 输入查询内容，比如想找某个功能的代码：

     qdrant-find query="计算器函数"
     

  2. 服务器会返回匹配的结果，每条信息单独显示，可能包含描述和元数据里的代码。
  3. 检查返回结果，找到你需要的内容。
• 小技巧: 查询越具体，结果越准确。比如 "计算器函数" 比 "函数" 更精准。

功能 3：自定义代码搜索

• 用途: 把服务器变成代码搜索工具，适合开发者使用。
• 配置步骤:
  1. 设置环境变量，调整工具描述：

     QDRANT_URL="http://localhost:6333" COLLECTION_NAME="code-snippets" \
     TOOL_STORE_DESCRIPTION="存储代码片段，information 是描述，metadata 包含代码" \
     TOOL_FIND_DESCRIPTION="根据描述搜索代码片段" \
     uvx mcp-server-qdrant --transport sse
     

  2. 在 Cursor 中配置服务器地址，比如 http://localhost:8000/sse。
  3. 保存代码：

     qdrant-store information="计算两数之和" metadata={"code": "def add(a, b): return a + b"}
     

  4. 搜索代码：

     qdrant-find query="两数相加的函数"
     

• 效果: 返回最匹配的代码片段，方便复用。

使用场景举例

1. 个人知识管理: 保存笔记或文档片段，随时用自然语言找回。
2. 团队协作: 在云端运行服务器，共享代码或知识库。
3. 本地开发: 用本地模式测试，不依赖网络。

注意事项

• 确保 Qdrant 服务已启动（本地或远程）。
• 默认嵌入模型是 sentence-transformers/all-MiniLM-L6-v2，只能用 FastEmbed 支持的模型。
• SSE 模式适合远程访问，stdio 适合本地客户端。