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：一个 Qdrant MCP 服务器

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

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

概述

用于在 Qdrant 向量搜索引擎中保存和检索记忆的官方 Model Context Protocol 服务器。它充当 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：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

提供了用于构建和运行 MCP 服务器的 Dockerfile：

# 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 中，您可以在设置中配置 MCP 服务器，通过 SSE 传输协议指向此正在运行的服务器。有关如何向 Cursor 添加 MCP 服务器的描述可以在 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 规则，以便在代理生成新的代码片段时始终使用 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 一起使用

如需一键安装，请点击以下安装按钮之一：

手动安装

在 VS Code 的用户设置（JSON）文件中添加以下 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 有建议，或者想报告错误，请提出问题！我们欢迎所有形式的贡献。

在本地测试 `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 文件。