Qdrant MCP

Qdrant MCP

一个 Model Context Protocol（MCP）服务，将 Qdrant 向量数据库的完整 API 封装为工具——集合管理、高级混合搜索、载荷与向量编辑、快照以及服务可观测性。不只是 store/find。

目录

• 概述
• 主要功能
• 要求
• 安装
  • PyPI
  • Docker
  • Claude Desktop bundle (.mcpb)
• 快速开始
• 连接到 Claude
  • Claude Desktop / Claude Code（本地，stdio）
  • 远程（streamable-http）
• 配置参考
• 可用工具
• 只读模式
• 架构
• 安全性
• 开发
• 版本管理与变更日志
• 许可证

概述

Qdrant MCP 是一个轻量的 MCP 服务，与 Qdrant API 一一对应：它为每项 Qdrant 操作注册一个工具，使用 Pydantic 验证输入，调用官方 qdrant-client SDK，并返回结果。它不会生成嵌入，不会解析文档，也不会决定如何对文本分块——它有意不作为 RAG 系统。LLM 客户端想要存储或查询什么，就由客户端自行提供向量。

这一专注点也使它有别于官方 Qdrant MCP 服务：后者只提供两个工具（store/find），并会代为嵌入文档。本服务涵盖 Qdrant 的其余功能——集合、点、搜索、载荷、索引、快照和可观测性等所有功能——让 LLM 客户端能够端到端地管理 Qdrant 部署，而不只是通过狭窄的接口推送和拉取记忆。

请参阅 ROADMAP.md，了解完整的分阶段设计历程，其中包括影响每项决策的所有发现（西班牙语）。

主要功能

• 完整的集合与点生命周期管理 — 创建／更新／删除集合，对点执行 CRUD 操作、滚动查询和计数。
• 支持 Qdrant 的所有搜索模式 — 对密集向量、稀疏向量和多向量执行普通向量搜索；混合搜索（RRF——可选加权——和 DBSF 融合）；嵌套多阶段预取（融合密集向量和稀疏向量，再使用多向量重新排序）；MMR 多样性搜索；自定义评分公式（载荷加权、时间衰减和地理衰减）；按载荷字段排序、随机采样、分组查询、推荐、发现和成对距离矩阵。每个搜索工具都接受搜索精度参数（search_params、score_threshold、分页和超时）。
• 载荷与向量编辑 — 设置／覆盖／删除／清空载荷、载荷索引、分面计数、命名（密集／稀疏）向量管理、按顺序批量操作。
• 快照 — 按集合和对整个存储进行备份／恢复。
• 别名、重新索引与查询 — 在不停机的情况下切换名称指向的集合；在服务端集合之间复制点（向量不会经过模型）；检查分片布局和优化器是否已完成索引；在编写过滤器前，查看集合实际包含哪些载荷键。
• 可观测性 — 遥测、Prometheus 指标端点、资源配额、自诊断问题。
• 按需启用工具 — 工具按工具集分组，需显式启用，因此默认不会向客户端提供 60 多个功能重叠的工具。
• 只读保护 — 一个标志即可从工具注册表中彻底移除所有可变更数据的工具。
• 节省模型上下文 — 服务端声明的架构精简紧凑（概述 Qdrant 冗长的 Filter 和配置模型，验证方式保持不变），因此默认工具集仅占用约 44 KB 的架构空间，而不是约 150 KB；每次调用的结果上限（QDRANT_MCP_MAX_LIMIT）可防止一次误设的 limit 淹没对话。
• 默认具备韧性 — 每次 Qdrant 调用都会通过带退避的重试机制，并在失败时返回 Qdrant 自身的错误消息，而非通用异常。

要求

• Python 3.12+
• Qdrant server v1.19.0 或更新版本。 两个工具 （qdrant_collection_vector_create／qdrant_collection_vector_delete）依赖某个端点；在较旧的 Qdrant server 上，该端点会返回 404（已在 v1.13.6 和 v1.15.1 上验证）——其他功能在较旧版本上也能使用，但本项目仅针对 v1.19.0+ 进行测试。

安装

PyPI

# Run without installing (recommended for Claude Desktop/Code configs)
uvx mcp-qdrant

# Or install into your environment
pip install mcp-qdrant

Docker

docker run --rm -p 8000:8000 \
  -e QDRANT_URL=http://host.docker.internal:6333 \
  -e QDRANT_MCP_TRANSPORT=streamable-http \
  -e QDRANT_MCP_HTTP_HOST=0.0.0.0 \
  -e QDRANT_MCP_SHARED_SECRET=<a long random secret> \
  ghcr.io/avaazquezz/qdrant-mcp:latest

此镜像仅适用于 streamable-http——stdio 需要客户端直接控制进程的 stdin/stdout，而分离运行的容器无法提供这种方式。服务默认绑定到 127.0.0.1，因此需要设置 QDRANT_MCP_HTTP_HOST=0.0.0.0，才能从容器外访问该端口。每次发布带标签的版本时，都会以 {version}、{major}.{minor} 和 latest 形式发布镜像。

Claude Desktop 安装包（.mcpb）

从最新版本下载 mcp-qdrant.mcpb，然后双击。Claude Desktop 会通过 uv 安装服务（在你的机器上解析依赖，无需安装 Python），并通过自身的设置表单提示你配置 Qdrant URL、API 密钥、本地路径、工具集和只读模式——无需编辑 JSON。

快速开始

通过 stdio 将服务指向本地 Qdrant 实例，并确认其可访问：

QDRANT_URL=http://localhost:6333 mcp-qdrant

从 MCP 客户端连接后，典型的首次交互如下：

1. qdrant_health_check — 在进行其他操作前，确认配置的 Qdrant 实例可访问。
2. qdrant_collection_create — {"collection_name": "docs", "vector_size": 4, "distance": "Cosine"}。
3. qdrant_points_upsert — {"collection_name": "docs", "points": [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"title": "hello"}}]}。
4. qdrant_query — {"collection_name": "docs", "query_vector": [0.1, 0.2, 0.3, 0.4], "limit": 5}。

每个工具的完整参数结构都在其 MCP schema 中说明 — 大模型客户端会通过 tools/list 直接读取这些信息；下方可用工具中的表格则是相同数据的易读摘要。

连接到 Claude

Claude Desktop / Claude Code（本地，stdio）

claude_desktop_config.json（Claude Desktop）或 .mcp.json（Claude Code）：

{
  "mcpServers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-qdrant"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_MCP_TOOLSETS": "core,search"
      }
    }
  }
}

也可以使用安装中介绍的 .mcpb 捆绑包 — 效果相同，无需编辑 JSON。

远程（streamable-http）

适用于可通过网络访问的服务（例如，在 Claude.ai 中添加为自定义连接器），并且只连接到一个固定的底层 Qdrant 实例。在此模式下，必须设置 QDRANT_MCP_SHARED_SECRET — 若未设置，服务将拒绝以 streamable-http 模式启动，以避免在网络上提供未经身份验证的端点（经实际验证：任何人只要有 URL，就能轻易使用开放的 streamable-http 服务）。

QDRANT_URL=http://localhost:6333 \
QDRANT_MCP_TRANSPORT=streamable-http \
QDRANT_MCP_HTTP_HOST=0.0.0.0 \
QDRANT_MCP_SHARED_SECRET=<a long random secret> \
mcp-qdrant

在 Claude.ai 中（Customize → Connectors → Add custom connector，已通过真实账号实际验证）：输入服务的 HTTPS URL，然后在检测到的身份验证界面中选择 "None"，并添加一个 Request header — Authorization → Bearer <the same secret>。 （此处使用 Authorization，因为它是 Claude.ai 自定义连接器界面接受的两个标头名称之一，无需 Anthropic 手动批准自定义名称。）

配置参考

所有配置都通过环境变量设置，并在启动时读取一次 — 配置错误会立即导致失败，而不会等到之后才以令人困惑的工具错误形式出现。

变量	默认值	必需	用途
QDRANT_URL	—	否¹	Qdrant 实例的 URL，例如 http://localhost:6333 或 Qdrant Cloud URL。
QDRANT_API_KEY	—	否	QDRANT_URL 的 API 密钥（如果实例需要）。
QDRANT_LOCAL_PATH	—	否¹	嵌入式／磁盘上的 Qdrant 实例路径，用于替代 URL。
QDRANT_MCP_READ_ONLY	false	否	从注册表中移除所有未标记为只读的工具。请参阅只读模式。
QDRANT_MCP_TRANSPORT	stdio	否	stdio（本地，用于 Claude Desktop/Code）或 streamable-http（网络）。
QDRANT_MCP_TOOLSETS	core	否	要注册的工具集列表，以逗号分隔。请参阅可用工具。
QDRANT_MCP_SHARED_SECRET	—	是，仅用于 streamable-http	客户端必须在 Authorization 标头中发送的 Bearer 令牌。
QDRANT_MCP_HTTP_HOST	127.0.0.1	否	streamable-http 的绑定主机。在容器中使用 0.0.0.0。
QDRANT_MCP_HTTP_PORT	8000	否	streamable-http 的绑定端口。
QDRANT_MCP_MAX_LIMIT	1000	否	单次工具调用可请求的最大点数（最小值为 30，以确保每个工具的默认请求都能满足）（limit、分组的 limit × group_size、批次总数、ID 数量等）。超出上限的请求会被拒绝，并提示进行分页，而不是静默截断。

¹ QDRANT_URL 和 QDRANT_LOCAL_PATH 互斥；如果两者都未设置，客户端会回退到 qdrant-client SDK 自身的默认值 localhost:6333。

可用工具

工具按工具集分组，通过 QDRANT_MCP_TOOLSETS（以逗号分隔）启用。默认仅启用 core，其余工具集需显式选择启用，因此客户端不会一次性获取所有工具：

• core — 集合和点的 CRUD 操作，以及 qdrant_query 和 qdrant_health_check 冒烟测试。仅凭这些工具集即可实现功能完整的 MCP。
• search — 除普通向量搜索之外的所有功能：批量／分组查询、推荐、发现和成对距离矩阵。
• payload — 负载编辑和索引、命名向量管理、有序批量点操作。
• snapshots — 集合和完整存储的备份／恢复。
• observability — 遥测、指标、配额和自诊断问题。
• admin — 集合别名、每个集合的分片布局和优化器进度，以及两种可让数据保留在服务端的组合操作：在集合之间复制点（实现零停机重新索引所缺少的另一半），以及分析集合实际拥有的负载键。此处所有功能都适用于单节点；分布式集群管理（分片键、重新分片）不在范围内 — 请参阅 ROADMAP.md 中的第 5 阶段和第 12 阶段。

下表由实时工具注册表直接生成 — 添加或更改工具后，运行 uv run python scripts/gen_tools_doc.py 以保持同步（如果内容不一致，CI 会导致构建失败）。

工具	工具集	只读	破坏性	幂等	描述
qdrant_health_check	core	✅	❌	✅	确认已配置的 Qdrant 实例可访问且正常响应。
qdrant_collection_create	core	❌	❌	❌	创建一个集合：可以是单个未命名向量（vector_size + distance），也可以是一个或多个命名向量（vectors，每个都是完整的 VectorParams — 包括大小、距离，以及可选的自身 multivector_config（用于 ColBERT 风格的多向量）或 quantization_config）——两者必须且只能选其一。
qdrant_collection_list	core	✅	❌	✅	列出已配置 Qdrant 实例中的所有集合名称。
qdrant_collection_info	core	✅	❌	✅	返回一个集合的完整配置和状态。
qdrant_collection_update	core	❌	❌	✅	更新现有集合的优化器、HNSW、集合或向量参数。
qdrant_collection_delete	core	❌	✅	✅	删除一个集合及其所有点；如果集合不存在，则不执行任何操作。
qdrant_collection_exists	core	✅	❌	✅	检查集合是否存在；若不存在，不会引发错误。
qdrant_points_upsert	core	❌	✅	✅	在集合中插入或替换点（ID + 向量 + 负载）。
qdrant_points_get	core	✅	❌	✅	按 ID 检索点；未知 ID 会直接省略，不会报错。
qdrant_points_delete	core	❌	✅	✅	按 ID 列表或负载筛选条件删除点——两者必须且只能选其一。
qdrant_points_scroll	core	✅	❌	✅	分页遍历集合中的所有点，可选择使用筛选条件。
qdrant_points_count	core	✅	❌	✅	统计集合中的点数，可选择按筛选条件匹配。
qdrant_query	core	✅	❌	✅	使用 Qdrant 统一查询 API 搜索集合：向量相似度、混合融合、多阶段重排、MMR 多样性、基于负载的分数公式、按负载字段排序或随机采样。
qdrant_query_batch	search	✅	❌	✅	在一次往返中对一个集合运行多个相互独立的查询——每个条目均可使用 qdrant_query 的所有查询模式和调优参数（普通向量、对预取结果进行融合、MMR、公式、order_by、sample、search_params、score_threshold、offset）；timeout_seconds 和 consistency 适用于整个批次。
qdrant_query_groups	search	✅	❌	✅	按负载字段对向量查询结果分组，每组最多返回 group_size 个命中结果——例如，每个源文档中匹配度最高的分块。
qdrant_recommend	search	✅	❌	✅	找出与一组正例相似、与一组负例不同的点（向量或点 ID）——Qdrant 的推荐 API。
qdrant_recommend_batch	search	✅	❌	✅	在一次往返中对一个集合运行多个相互独立的推荐查询。
qdrant_recommend_groups	search	✅	❌	✅	按负载字段对推荐查询结果分组，每组最多返回 group_size 个命中结果。
qdrant_discover	search	✅	❌	✅	根据点在正负上下文对（向量或点 ID）中与目标的契合程度进行排序——Qdrant 的发现搜索，是比推荐更精细的替代方案。
qdrant_discover_batch	search	✅	❌	✅	在一次往返中对一个集合运行多个相互独立的发现查询。
qdrant_distance_matrix_pairs	search	✅	❌	✅	随机采样点之间的成对距离矩阵：对于 sample 个点中的每个点，返回同一采样中的 limit 个最近邻——结果为扁平列表，包含 (a, b, score) 对。
qdrant_distance_matrix_offsets	search	✅	❌	✅	与 qdrant_distance_matrix_pairs 相同的距离矩阵，但采用按列组织的结构（指向共享 ID 列表的偏移量 + 并行分数数组）——适用于大型采样，结构更紧凑。
qdrant_payload_set	payload	❌	❌	✅	将字段合并到所选点的负载中——ids/points_filter 必须且只能选其一。
qdrant_payload_overwrite	payload	❌	✅	✅	使用 payload 替换所选点的整个负载——ids/points_filter 必须且只能选其一。
qdrant_payload_delete	payload	❌	✅	✅	删除所选点的指定负载键——ids/points_filter 必须且只能选其一。
qdrant_payload_clear	payload	❌	✅	✅	清除所选点的整个负载，但保留其向量——ids/points_filter 必须且只能选其一。
qdrant_payload_facet	payload	✅	❌	✅	统计集合（或筛选后的子集）中某个负载字段的不同值数量——例如，统计每个 city 对应的点数。
qdrant_payload_index_create	payload	❌	❌	✅	为 field_name 创建负载索引，加快使用该字段的筛选操作。
qdrant_payload_index_delete	payload	❌	✅	✅	删除 field_name 上的负载索引。
qdrant_collection_vector_create	payload	❌	❌	✅	向已有点的集合添加新的命名向量（稠密或稀疏），而不改动这些点。
qdrant_collection_vector_delete	payload	❌	✅	✅	从集合中移除命名向量（稠密或稀疏）——点会保留其其他向量和负载。
qdrant_points_batch_update	payload	❌	✅	❌	在单个请求中，按给定顺序对一个集合运行多个点操作（upsert、删除、设置/覆盖/删除/清除负载、更新/删除向量）。
qdrant_vectors_update	payload	❌	✅	✅	按 ID 替换现有点的向量——不更改其负载。
qdrant_vectors_delete	payload	❌	✅	✅	从所选点中移除指定的命名向量，同时保留其负载和其他向量——ids/points_filter 必须且只能选其一。
qdrant_alias_list	admin	✅	❌	✅	列出服务上的所有别名及其指向的集合。
qdrant_collection_aliases	admin	✅	❌	✅	列出指向某个集合的别名（如果没有，则返回空列表）。
qdrant_alias_update	admin	❌	✅	❌	创建、重命名、重新指向或删除别名——这是实现零停机重建索引的基础：先构建新集合，再切换客户端使用的别名。
qdrant_collection_cluster_info	admin	✅	❌	✅	集合的分片布局：分片数量，以及每个本地分片的点数和副本状态。
qdrant_collection_optimizations	admin	✅	❌	✅	集合后台优化器的进度——可用于判断“索引是否已完成？”以及“集合为什么不是绿色状态？”。
qdrant_collection_copy	admin	❌	✅	✅	在同一 Qdrant 实例中的两个集合之间复制点（所有向量——稠密、稀疏和多向量——以及负载），完全在服务端执行：向量不会经过模型。
qdrant_payload_schema_infer	admin	✅	❌	✅	分析集合中实际出现的负载键，以便根据真实键而非猜测的键编写筛选条件。
qdrant_snapshot_create	snapshots	❌	❌	❌	创建一个集合当前状态的快照。
qdrant_snapshot_list	snapshots	✅	❌	✅	列出为某个集合存储的快照。
qdrant_snapshot_delete	snapshots	❌	✅	✅	删除集合快照，释放服务上的磁盘空间——不会影响实时集合。
qdrant_snapshot_recover	snapshots	❌	✅	✅	将 collection_name 覆盖为快照中记录的状态——该快照之后写入的所有内容都会丢失。
qdrant_snapshot_download	snapshots	✅	❌	✅	确认集合快照存在并返回其获取地址——此工具不会传输快照文件本身（它可能非常大）；请自行从返回的 url 下载（例如使用 curl）。
qdrant_storage_snapshot_create	snapshots	❌	❌	❌	创建整个存储的快照（包括所有集合和服务配置），而非仅创建某个集合的快照。
qdrant_storage_snapshot_list	snapshots	✅	❌	✅	列出服务上存储的完整存储快照。
qdrant_storage_snapshot_delete	snapshots	❌	✅	✅	删除完整存储快照，释放其占用的磁盘空间。
qdrant_storage_snapshot_download	snapshots	✅	❌	✅	确认完整存储快照存在并返回其获取地址——注意事项与 qdrant_snapshot_download 相同：此工具不会传输文件本身。
qdrant_telemetry	observability	✅	❌	✅	服务级遥测信息：构建信息、各集合统计数据、请求计数器、内存和硬件用量。
qdrant_metrics_prometheus	observability	✅	❌	✅	返回 Qdrant 提供 Prometheus 格式指标的 URL——此工具不会获取指标本身（它们是纯文本，而非 JSON）；请将 Prometheus 抓取器指向返回的 url。
qdrant_quotas_get	observability	✅	❌	✅	当前的服务级资源配额（内存/磁盘限制）及实际用量。
qdrant_quotas_set	observability	❌	❌	✅	更新服务级资源配额。
qdrant_issues_list	observability	✅	❌	✅	列出 Qdrant 检测到的自身配置问题（例如，频繁用于筛选但未建立负载索引的字段）。
qdrant_issues_clear	observability	❌	✅	✅	清除所有累积的问题。

只读模式

设置 QDRANT_MCP_READ_ONLY=1 会将 destructiveHint 未明确设为 false 的所有工具（即任何 readOnlyHint 不为 true 的工具）直接从注册表中移除——调用 tools/list 的客户端根本看不到这些工具，而不是能看到它们但调用会被拒绝。这是让 LLM 客户端安全地只读访问 Qdrant 部署的 机制：将其指向你的数据库，设置此标志，就不会留下任何可供其写入数据的代码路径。

架构

• 单个共享客户端。 启动时只创建一个 AsyncQdrantClient，并由每个工具共同使用。
• 单一注册关口。 每个工具模块都会调用同一个 ToolRegistry，工具集筛选和只读保护都在这里执行——工具无法通过采用不同方式注册来绕过 任一机制。
• 弹性。 每次 Qdrant 调用都会通过基于 tenacity 的重试和退避机制进行包装（qdrant-client SDK 本身只提供超时功能，不提供重试），并将错误转换为携带 Qdrant 自身错误消息的 MCP ToolError，而不是通用错误——因此，“集合不存在”会原样显示为“集合不存在”。
• stdio 安全日志记录。 所有日志都会写入 stderr，并且在 MCP 服务对象构造之前完成配置——在 stdio 传输下写入 stdout 会破坏 JSON-RPC 消息的帧结构。

安全性

• streamable-http 必须进行身份验证。 如果未设置 QDRANT_MCP_SHARED_SECRET，服务将拒绝启动——我们已通过实际测试验证，任何知道 URL 的人都能轻易使用未经身份验证的实例。
• 全面验证输入。 每个工具的输入都是 Pydantic 模型——格式错误的输入会在到达 Qdrant SDK 之前被拒绝，并返回结构化错误。
• 只读保护。 QDRANT_MCP_READ_ONLY 会将所有可变更数据的工具从注册表中移除——参见只读模式。

开发

git clone https://github.com/avaazquezz/Qdrant-MCP.git
cd Qdrant-MCP
uv sync --dev
uv run pre-commit install

uv run ruff check .            # lint
uv run ruff format --check .   # formatting
uv run mypy .                  # type checking (strict)
uv run pytest                  # unit tests
uv run pytest -m integration   # integration tests — needs a running Qdrant (CI runs one as a Docker service)

如果添加或修改工具，请重新生成可用工具中的表格，而不是手动编辑：

uv run python scripts/gen_tools_doc.py          # regenerate
uv run python scripts/gen_tools_doc.py --check  # verify, no changes (what CI runs)

版本管理与更新日志

本项目遵循语义化版本。有关发布说明，请参见 CHANGELOG.md；有关各版本背后的分阶段设计历史，请参见 ROADMAP.md。

许可证

MIT