Qdrant MCP Server

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

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

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

概述

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

组件

工具

1. qdrant-store
   • 在 Qdrant 数据库中存储一些信息
   • 输入：
     • information (字符串)：要存储的信息
     • metadata (JSON)：要存储的可选元数据
     • collection_name (字符串)：用于存储信息的集合名称。如果没有默认集合名称，则此字段为必填项。 如果存在默认集合名称，则此字段不可用。
   • 返回：确认消息
2. 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：服务器发送事件传输，非常适合远程客户端
• 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 服务器转换为专门的代码搜索工具，可以：

1. 存储代码片段、文档和实现细节
2. 基于语义搜索检索相关代码示例
3. 帮助开发人员查找特定的实现或使用模式

您可以通过存储代码片段的自然语言描述（在 information 参数中） 以及实际代码（在 metadata.code 属性中）来填充数据库，然后使用描述您要查找内容的自然语言查询 进行搜索。

[!NOTE] 上面提供的工具描述是示例，可能需要根据您的特定用例进行自定义。考虑 调整描述以更好地匹配您团队的工作流程以及您要存储和检索的特定类型的代码片段。

如果您已成功安装 mcp-server-qdrant，但仍然无法使其与 Cursor 配合使用，请 考虑创建 Cursor 规则，以便在 代理生成新代码片段时始终使用 MCP 工具。 您可以将规则限制为仅适用于某些文件类型，以避免将 MCP 服务器用于文档或其他类型的内容。

与 Claude Code 一起使用

您可以通过将其连接到此 MCP 服务器来增强 Claude Code 的功能，从而对您现有的代码库进行语义搜索。

设置 mcp-server-qdrant

1. 将 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
   

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 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 文件。