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 数据库中的信息

环境变量

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

名称	描述	默认值
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_URL 和 QDRANT_LOCAL_PATH。

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

FastMCP 环境变量

由于 mcp-server-qdrant 基于 FastMCP，因此它也支持所有 FastMCP 的环境变量。其中最重要的如下：

环境变量	描述	默认值
FASTMCP_DEBUG	启用调试模式	false
FASTMCP_LOG_LEVEL	设置日志级别（DEBUG、INFO、WARNING、ERROR、CRITICAL）	INFO
FASTMCP_HOST	服务器绑定的主机地址	127.0.0.1
FASTMCP_PORT	服务器运行的端口	8000
FASTMCP_WARN_ON_DUPLICATE_RESOURCES	显示重复资源警告	true
FASTMCP_WARN_ON_DUPLICATE_TOOLS	显示重复工具警告	true
FASTMCP_WARN_ON_DUPLICATE_PROMPTS	显示重复提示警告	true
FASTMCP_DEPENDENCIES	服务器环境中要安装的依赖列表	[]

安装

使用 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_PORT 环境变量更改。

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

使用 Docker

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

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

# 运行容器
docker run -p 8000:8000 \
  -e FASTMCP_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

[!提示] 请注意，我们将 FASTMCP_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 一起使用，它们都内置了对 Model Context 协议的支持。

与 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

[!提示] 我们建议使用 SSE 传输作为连接 Cursor/Windsurf 与 MCP 服务器的首选方式，因为它支持远程连接。这使得与团队共享服务器或在云环境中使用它变得更加容易。

此配置将 Qdrant MCP 服务器转变为一个专门的代码搜索工具，它可以：

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

您可以将代码片段的自然语言描述（在 information 参数中）与实际代码（在 metadata.code 属性中）一起存储到数据库中，然后使用描述您所寻找内容的自然语言查询来搜索它们。

[!注意] 上面提供的工具描述仅为示例，可能需要根据您的具体用例进行定制。请考虑调整描述，使其更好地匹配您团队的工作流程以及您希望存储和检索的特定类型代码片段。

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

与 Claude Code 配合使用

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

设置 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 服务器可以使用 mcp dev 命令以开发模式运行。这将启动服务器并在您的浏览器中打开 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 的改进有任何建议，或想报告一个 bug，请提交一个问题！我们非常欢迎各种形式的贡献。

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

mcp-server-qdrant 快速上手指南

mcp-server-qdrant 是一个基于 Model Context Protocol (MCP) 的服务器，用于将大语言模型（LLM）与 Qdrant 向量数据库连接。它充当语义记忆层，支持存储和检索信息，适用于构建 AI 驱动的 IDE、聊天机器人或自定义工作流。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)。
• Python 环境：推荐使用 uv 工具链（包含 uvx），它会自动管理运行时依赖。
  • 安装 uv: curl -LsSf https://astral.sh/uv/install.sh | sh
• Qdrant 实例：
  • 云端/远程：拥有一个运行中的 Qdrant 服务 URL 和 API Key。
  • 本地：安装并运行本地 Qdrant 服务，或准备一个本地存储路径。
• 网络加速（可选）：由于默认嵌入模型 sentence-transformers/all-MiniLM-L6-v2 需要从 Hugging Face 下载，国内用户建议配置镜像源：

  export HF_ENDPOINT=https://hf-mirror.com
  

安装与运行

本工具无需传统“安装”，推荐使用 uvx 直接运行，或通过 Docker 部署。

方式一：使用 uvx 运行（推荐）

这是最快捷的方式，uvx 会自动拉取最新版本的工具并执行。

基本命令：

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant

配置说明：

• QDRANT_URL: Qdrant 服务地址。如果是本地默认启动，通常为 http://localhost:6333。
• COLLECTION_NAME: 指定要操作的集合名称。如果集合不存在，服务器会自动创建。
• EMBEDDING_MODEL: 使用的嵌入模型（目前主要支持 FastEmbed 兼容模型）。

切换传输协议（用于远程客户端）： 默认使用 stdio（标准输入输出），若需通过 HTTP/SSE 连接（如 Cursor 远程模式），请添加 --transport 参数：

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

方式二：使用 Docker 运行

适合需要隔离环境或部署在服务器的场景。

# 构建镜像
docker build -t mcp-server-qdrant .

# 运行容器
docker run -p 8000:8000 \
  -e FASTMCP_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

注意：Docker 模式下必须设置 FASTMCP_HOST="0.0.0.0" 以允许外部访问。

基本使用

启动服务器后，它会自动暴露两个核心工具供 MCP 客户端（如 Claude Desktop, Cursor, Windsurf）调用。

1. 配置 MCP 客户端

以 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": "knowledge-base",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

如果是本地 Qdrant 模式：

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_LOCAL_PATH": "/absolute/path/to/qdrant/storage",
      "COLLECTION_NAME": "local-memory",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

2. 功能演示

配置完成后，重启客户端即可在对话中使用以下功能：

• 存储记忆 (qdrant-store)

  • 用途：将文本信息及其元数据存入向量库。
  • 示例交互：

    "请记住这段代码片段：功能是计算斐波那契数列。代码内容是 def fib(n): ...。" (系统会自动调用 qdrant-store，将描述作为 information，代码作为 metadata 存储)

• 检索记忆 (qdrant-find)

  • 用途：根据自然语言查询检索相关上下文。
  • 示例交互：

    "我之前存过关于斐波那契数列的代码吗？找出来给我看看。" (系统会自动调用 qdrant-find，进行语义搜索并返回结果)

3. 进阶场景：作为代码搜索工具

你可以自定义工具描述，将其集成到 Cursor 或 Windsurf 中作为专用代码库搜索引擎。

启动命令示例（带自定义描述）：

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets. 'information' should be a natural language description of the code logic. Actual code must be in 'metadata' under the 'code' key." \
TOOL_FIND_DESCRIPTION="Search for code snippets based on natural language descriptions of functionality." \
uvx mcp-server-qdrant --transport sse

然后在 Cursor 设置中添加 MCP 服务器地址：http://localhost:8000/sse。这样 AI 就能根据你的自然语言描述，精准查找项目中已有的代码实现。