Qdrant MCP

官方

使用 Qdrant 向量数据库进行语义搜索。

你可以用 Qdrant MCP 做什么?

  • 存储记忆 — 让助手将信息(可选附带元数据)保存到 Qdrant 集合中,使用 qdrant-store。
  • 语义搜索 — 使用自然语言 query 和 qdrant-find 检索相关的已存储信息。
  • 选择集合 — 每次调用时指定目标 collection_name,或通过 COLLECTION_NAME 设置默认值。
  • 自定义工具描述 — 调整 TOOL_STORE_DESCRIPTION 和 TOOL_FIND_DESCRIPTION,将服务器改造成代码片段搜索工具。
  • 只读模式 — 启用 QDRANT_READ_ONLY 以禁用存储功能,仅允许检索。
  • 调整结果 — 使用 QDRANT_SEARCH_LIMIT 限制搜索结果数量,并通过 EMBEDDING_MODEL 选择嵌入模型。

文档

mcp-server-qdrant:Qdrant MCP 服务器

smithery badge

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

此仓库展示了如何为 Qdrant(一种向量搜索引擎)创建 MCP 服务器。

概述

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

组件

工具

  1. qdrant-store
    • 在 Qdrant 数据库中存储信息
    • 输入:
      • information (string):要存储的信息
      • metadata (JSON):要存储的可选元数据
      • collection_name (string):用于存储信息的集合名称。如果没有默认集合名称,则此字段为必填项。 如果已设置默认集合名称,则此字段不可用。
    • 返回:确认消息
  2. qdrant-find
    • 从 Qdrant 数据库中检索相关信息
    • 输入:
      • query (string):用于搜索的查询
      • collection_name (string):用于存储信息的集合名称。如果没有默认集合名称,则此字段为必填项。 如果已设置默认集合名称,则此字段不可用。
    • 返回:以独立消息形式返回存储在 Qdrant 数据库中的信息

环境变量

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

[!NOTE] 不能同时提供 QDRANT_URL 和 QDRANT_LOCAL_PATH。

名称描述默认值
QDRANT_URLQdrant 服务器的 URLNone
QDRANT_API_KEYQdrant 服务器的 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_DESCRIPTIONstore 工具的自定义描述参见 settings.py 中的默认值
TOOL_FIND_DESCRIPTIONfind 工具的自定义描述参见 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_DEBUG启用调试模式false
FASTMCP_HOST服务器绑定的主机地址(SSE 和 HTTP 传输)127.0.0.1
FASTMCP_PORT服务器运行的端口(SSE 和 HTTP 传输)8000
FASTMCP_MASK_ERROR_DETAILS隐藏发送给客户端的工具错误消息中的异常详情false

[!NOTE] 在 0.9.0 版本之前,这些设置使用 FASTMCP_SERVER_ 前缀,例如 FASTMCP_SERVER_HOST。 旧的 FASTMCP_SERVER_HOST、FASTMCP_SERVER_PORT 和 FASTMCP_SERVER_DEBUG 名称仍然有效,但已弃用, 并将在未来版本中移除。如果同时设置了新旧名称,则以新名称为准。

安装

使用 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 服务器:

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
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

[!TIP] 请注意,我们将 FASTMCP_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 的设置中配置 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 服务器转换为专用代码搜索工具,可用于:

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

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

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

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

与 Claude Code 配合使用

通过将 Claude Code 连接到此 MCP 服务器,你可以增强其功能,并对现有代码库进行语义搜索。

设置 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 配合使用

如需一键安装,请点击以下任一安装按钮:

Install with UVX in VS Code Install with UVX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

手动安装

将以下 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 文件。

隐私与支持