mcp-server-qdrant: A Qdrant MCP server

mcp-server-qdrant：Qdrant MCP 服务

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

此仓库展示了如何为 Qdrant 创建 MCP 服务。Qdrant 是一款向量搜索引擎。

概述

一个官方的 Model Context Protocol 服务，用于在 Qdrant 向量搜索引擎中保存和检索记忆。 它作为构建在 Qdrant 数据库之上的语义记忆层。

组件

工具

1. qdrant-store
   • 在 Qdrant 数据库中保存信息
   • 输入：
     • information（字符串）：要保存的信息
     • metadata（JSON）：要保存的可选元数据
     • collection_name（字符串）：要保存信息的集合名称。如果没有默认集合名称，此字段为必填项。 如果存在默认集合名称，则不会启用此字段。
   • 返回：确认消息
2. qdrant-find
   • 从 Qdrant 数据库中检索相关信息
   • 输入：
     • query（字符串）：用于搜索的查询
     • collection_name（字符串）：要保存信息的集合名称。如果没有默认集合名称，此字段为必填项。 如果存在默认集合名称，则不会启用此字段。
   • 返回：以单独消息形式返回保存在 Qdrant 数据库中的信息

环境变量

通过环境变量进行配置。唯一的命令行参数是 --transport，用于选择传输协议。

说明

不能同时提供 QDRANT_URL 和 QDRANT_LOCAL_PATH。

名称	描述	默认值
QDRANT_URL	Qdrant 服务的 URL	None
QDRANT_API_KEY	Qdrant 服务的 API 密钥	None
COLLECTION_NAME	要使用的默认集合名称。	None
QDRANT_LOCAL_PATH	本地 Qdrant 数据库的路径（QDRANT_URL 的替代项）	None
EMBEDDING_PROVIDER	要使用的嵌入提供方（目前仅支持 "fastembed"）	fastembed
EMBEDDING_MODEL	要使用的嵌入模型名称	sentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTION	store 工具的自定义描述	默认值见 settings.py
TOOL_FIND_DESCRIPTION	find 工具的自定义描述	默认值见 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	要在服务环境中安装的依赖项列表	[]

说明

服务专用设置使用 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

提示

请注意，我们将 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 搭配使用，这两者都内置了对模型上下文 协议的支持。

与 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

提示

我们建议使用 SSE 传输协议连接 Cursor/Windsurf 与 MCP 服务，因为它支持远程连接。这样便于与你的团队共享服务，或在云环境中使用。

此配置会将 Qdrant MCP 服务转换为专用的代码搜索工具，可以：

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

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

说明

上述工具描述仅为示例，可能需要根据你的具体使用场景进行自定义。可以调整描述，使其更符合团队的工作流以及你想要存储和检索的代码片段类型。

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

与 Claude Code 配合使用

将 Claude Code 连接到此 MCP 服务，即可增强其能力，对现有代码库进行语义搜索。

设置 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="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 Inspector。

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，请提交一个 issue！ 我们欢迎所有贡献。

在本地测试 mcp-server-qdrant

MCP inspector 是一款用于测试和调试 MCP 服务的开发者工具。它同时运行一个客户端 UI（默认端口为 5173）和一个 MCP 代理服务（默认端口为 3000）。在浏览器中打开客户端 UI 即可使用 inspector。

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

启动后，在浏览器中打开 http://localhost:5173，即可访问 inspector 界面。

许可证

此 MCP 服务采用 Apache License 2.0 许可。这意味着你可以自由使用、修改和分发该软件，但须遵守 Apache License 2.0 的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。

隐私与支持

• 隐私政策
• 支持