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

模型上下文协议（MCP）是一个开放协议，它能够实现大型语言模型（LLM）应用程序与外部数据源和工具的无缝集成。无论您是在构建一个 AI 驱动的 IDE、增强一个聊天界面，还是在创建自定义 AI 工作流，MCP 都提供了一种标准化的方式来连接 LLM 与它们所需的内容。

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

概述

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

组件

工具

qdrant-store
- 将一些信息存储到 Qdrant 数据库中
- 输入：
  - information (string): 要存储的信息
  - metadata (JSON): 可选的元数据，用于存储
  - collection_name (string): 存储信息的集合名称。如果没有默认集合名称，此字段是必需的。如果有默认集合名称，此字段将禁用。
- 返回：确认消息
qdrant-find
- 从 Qdrant 数据库中检索相关信息
- 输入：
  - query (string): 用于搜索的查询
  - collection_name (string): 存储信息的集合名称。如果没有默认集合名称，此字段是必需的。如果有默认集合名称，此字段将禁用。
- 返回：存储在 Qdrant 数据库中的信息，作为单独的消息

环境变量

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

名称	描述	默认值
`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`	存储工具的自定义描述	见 `settings.py` 中的默认值
`TOOL_FIND_DESCRIPTION`	查找工具的自定义描述	见 `settings.py` 中的默认值

注意：您不能同时提供 QDRANT_URL 和 QDRANT_LOCAL_PATH。

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

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

[!TIP] 请注意，我们设置了 FASTMCP_HOST="0.0.0.0" 以使服务器监听所有网络接口。当在 Docker 容器中运行服务器时，这是必要的。

通过 Smithery 安装

要通过 Smithery 自动安装 Qdrant MCP 服务器为 Claude Desktop：

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="存储可重用的代码片段以供以后检索。'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

[!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：

# 添加配置为代码搜索的 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

验证服务器是否已添加：
```
claude mcp list
```

在 Claude Code 中使用语义代码搜索

工具描述，指定在 TOOL_STORE_DESCRIPTION 和 TOOL_FIND_DESCRIPTION 中，指导 Claude Code 如何使用 MCP 服务器。上面提供的是示例，可能需要根据您的具体用例进行自定义。但是，Claude Code 应该已经能够：

使用 qdrant-store 工具存储带有描述的代码片段
使用 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 的建议，或者想要报告一个错误，请打开一个问题！我们欢迎所有和任何形式的贡献。

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

qdrant/mcp-server-qdrant

星标增长

证据时间轴

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

概述

组件

工具

环境变量

FastMCP 环境变量

安装

使用 uvx

传输协议

使用 Docker

通过 Smithery 安装

手动配置 Claude Desktop

对其他工具的支持

与 Cursor/Windsurf 一起使用

与 Claude Code 一起使用

设置 mcp-server-qdrant

在 Claude Code 中使用语义代码搜索

以开发模式运行 MCP 服务器

与 VS Code 一起使用

手动安装

贡献

本地测试 `mcp-server-qdrant`

许可证

qdrant/mcp-server-qdrant

星标增长

证据时间轴

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

概述

组件

工具

环境变量

FastMCP 环境变量

安装

使用 uvx

传输协议

使用 Docker

通过 Smithery 安装

手动配置 Claude Desktop

对其他工具的支持

与 Cursor/Windsurf 一起使用

与 Claude Code 一起使用

设置 mcp-server-qdrant

在 Claude Code 中使用语义代码搜索

以开发模式运行 MCP 服务器

与 VS Code 一起使用

手动安装

贡献

本地测试 mcp-server-qdrant

许可证

本地测试 `mcp-server-qdrant`