Qdrant MCP
A Model Context Protocol (MCP) server that exposes the full vector database API as tools — collection management, advanced hybrid search, payload and vector editing, snapshots, and server observability. Not just /.
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
uvx mcp-qdrant==2.12.0Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
QDRANT_URL=<value> QDRANT_API_KEY=<secret> QDRANT_LOCAL_PATH=<value> QDRANT_MCP_TOOLSETS=<value> QDRANT_MCP_READ_ONLY=<value> QDRANT_MCP_MAX_LIMIT=<value> QDRANT_MCP_SNAPSHOT_ALLOWED_ORIGINS=<value> FASTEMBED_CACHE_PATH=<value> claude mcp add io.github.avaazquezz-mcp-qdrant -- uvx mcp-qdrant==2.12.0รันในเทอร์มินัล
{ "mcpServers": { "io.github.avaazquezz-mcp-qdrant": { "command": "uvx", "args": [ "mcp-qdrant==2.12.0" ], "env": { "QDRANT_URL": "<value>", "QDRANT_API_KEY": "<secret>", "QDRANT_LOCAL_PATH": "<value>", "QDRANT_MCP_TOOLSETS": "<value>", "QDRANT_MCP_READ_ONLY": "<value>", "QDRANT_MCP_MAX_LIMIT": "<value>", "QDRANT_MCP_SNAPSHOT_ALLOWED_ORIGINS": "<value>", "FASTEMBED_CACHE_PATH": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
A Model Context Protocol (MCP) server that exposes the full vector database API as tools — collection management, advanced hybrid search, payload and vector editing, snapshots, and server observability. Not just /.
The full Qdrant API as 58 MCP tools: plain-text semantic/BM25/hybrid search and a search advisor.
storefindQdrant MCP is a thin MCP server that wraps the Qdrant API
one-to-one: it registers a tool per Qdrant operation, validates the input with Pydantic, calls
the official qdrant-client SDK, and returns the result. It never generates embeddings, never
parses documents, and never decides how to chunk text — it is not a RAG system, on purpose.
Whatever an LLM client wants to store or query, it brings its own vectors.
That focus is also what sets it apart from the official Qdrant MCP
server, which exposes exactly two tools
(store/find) and does embed documents for you. This server covers the rest of Qdrant's
surface — everything under collections, points, search, payload, indexing, snapshots, and
observability — so an LLM client can manage a Qdrant deployment end to end, not just push and
pull memories through a narrow interface.
See ROADMAP.md for the full phase-by-phase design history, including every finding that shaped a decision (in Spanish).
search_params, score_threshold, paging, timeouts) are accepted by every search tool.Filter and configuration models are summarized, validation unchanged), so the
default toolset costs ~44 KB of schema instead of ~150 KB, and a per-call result cap
(QDRANT_MCP_MAX_LIMIT) stops one mistaken limit from flooding the conversation.qdrant_collection_vector_create/qdrant_collection_vector_delete) depend on an endpoint
that returns 404 on older Qdrant servers (verified against v1.13.6 and v1.15.1) — everything
else works on older versions, but v1.19.0+ is the only version this project tests against.# Run without installing (recommended for Claude Desktop/Code configs)
uvx mcp-qdrant
# Or install into your environment
pip install mcp-qdrant
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
The image only makes sense with streamable-http — stdio needs a client to own the process's
stdin/stdout directly, which a detached container can't provide. The server binds
127.0.0.1 by default, so QDRANT_MCP_HTTP_HOST=0.0.0.0 is required for the port to be
reachable from outside the container. Images are published on every tagged release as
{version}, {major}.{minor}, and latest.
.mcpb)Download mcp-qdrant.mcpb from the latest release
and double-click it. Claude Desktop installs the server via uv (resolving dependencies on your
machine, no Python installation required) and prompts for Qdrant URL, API key, local path,
toolsets, and read-only mode through its own settings form — no JSON to edit.
Point the server at a local Qdrant instance over stdio and confirm it's reachable:
QDRANT_URL=http://localhost:6333 mcp-qdrant
Once connected from an MCP client, a typical first exchange looks like:
qdrant_health_check — confirms the configured Qdrant instance is reachable before
doing anything else.qdrant_collection_create — {"collection_name": "docs", "vector_size": 4, "distance": "Cosine"}.qdrant_points_upsert — {"collection_name": "docs", "points": [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"title": "hello"}}]}.qdrant_query — {"collection_name": "docs", "query_vector": [0.1, 0.2, 0.3, 0.4], "limit": 5}.The full parameter shape of every tool is described in its own MCP schema — an LLM client reads
those directly via tools/list; the table in Available Tools below is a
human-readable summary of the same data.
stdio)claude_desktop_config.json (Claude Desktop) or .mcp.json (Claude Code):
{
"mcpServers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-qdrant"],
"env": {
"QDRANT_URL": "http://localhost:6333",
"QDRANT_MCP_TOOLSETS": "core,search"
}
}
}
}
Or use the .mcpb bundle described in Installation — same
result, no JSON to edit.
streamable-http)For a server reachable over the network (e.g. added as a custom connector in Claude.ai) with a
single, fixed backing Qdrant. QDRANT_MCP_SHARED_SECRET is required in this mode — the
server refuses to start as streamable-http without one, to avoid serving an unauthenticated
endpoint over the network (verified hands-on: an open streamable-http server is trivially
usable by anyone with the URL).
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
In Claude.ai (Customize → Connectors → Add custom connector, verified hands-on against a
real account): enter the server's HTTPS URL, then on the detected authentication screen choose
"None" and add a Request header — Authorization → Bearer <the same secret>.
(Authorization is used here because it's one of the two header names Claude.ai's
custom-connector UI accepts without requiring Anthropic's manual approval of a custom name.)
All configuration is via environment variables, read once at startup — a misconfiguration fails immediately instead of surfacing later as a confusing tool error.
¹ QDRANT_URL and QDRANT_LOCAL_PATH are mutually exclusive; if neither is set, the client
falls back to the qdrant-client SDK's own default of localhost:6333.
Tools are grouped into toolsets, enabled via QDRANT_MCP_TOOLSETS (comma-separated). Only
core is enabled by default — the rest are explicit opt-ins, so a client isn't handed every
tool at once:
core — collection and point CRUD, plus qdrant_query and the qdrant_health_check
smoke test. Enough for a fully working MCP on its own.search — everything beyond plain vector search: batched/grouped queries, recommend,
discover, and pairwise distance matrices.payload — payload editing and indexing, named-vector management, ordered batch point
operations.snapshots — collection and full-storage backup/restore.observability — telemetry, metrics, quotas, and self-diagnosed issues.admin — collection aliases, per-collection shard layout and optimizer progress, and two
composite operations that keep the data on the server: copying points between collections
(the missing half of a zero-downtime reindex) and profiling the payload keys a collection
really has. Everything here works on a single node; distributed-cluster administration (shard
keys, resharding) is out of scope — see ROADMAP.md, Fase 5 and Fase 12.The table below is generated directly from the live tool registry — run
uv run python scripts/gen_tools_doc.py after adding or changing a tool to keep it in sync
(CI fails the build if it drifts).
Setting QDRANT_MCP_READ_ONLY=1 removes every tool whose destructiveHint isn't explicitly
false (i.e. anything that isn't readOnlyHint=true) from the registry itself — a client
calling tools/list never sees them, rather than seeing them and having calls rejected. This is
the mechanism to hand an LLM client safe, read-only access to a Qdrant deployment: point it at
your database, set the flag, and there is no code path left for it to write anything.
AsyncQdrantClient is built once at startup and closed over
by every tool.ToolRegistry, which
is where the toolset filter and the read-only guard are both enforced — a tool can't bypass
either by registering itself differently.tenacity-based retry and backoff (the
qdrant-client SDK itself only exposes a timeout, not retries), and translated into an MCP
ToolError carrying Qdrant's own error message instead of a generic failure — so "collection
not found" reads as exactly that.stdio-safe logging. All logging goes to stderr, configured before the MCP server
object is even constructed — writing to stdout under the stdio transport would corrupt the
JSON-RPC message framing.streamable-http. The server refuses to start without
QDRANT_MCP_SHARED_SECRET — verified hands-on that an unauthenticated instance is trivially
usable by anyone with the URL.QDRANT_MCP_READ_ONLY removes every mutating tool from the registry —
see Read-Only Mode.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)
If you add or change a tool, regenerate the table in Available Tools rather than hand-editing it:
uv run python scripts/gen_tools_doc.py # regenerate
uv run python scripts/gen_tools_doc.py --check # verify, no changes (what CI runs)
This project follows Semantic Versioning. See CHANGELOG.md for release notes and ROADMAP.md for the phased design history behind each version.
The full Qdrant API as 58 MCP tools: plain-text semantic/BM25/hybrid search and a search advisor.
{ "mcpServers": { "io.github.avaazquezz-mcp-qdrant": { "command": "uvx", "args": [ "mcp-qdrant==2.12.0" ], "env": { "QDRANT_URL": "<value>", "QDRANT_API_KEY": "<secret>", "QDRANT_LOCAL_PATH": "<value>", "QDRANT_MCP_TOOLSETS": "<value>", "QDRANT_MCP_READ_ONLY": "<value>", "QDRANT_MCP_MAX_LIMIT": "<value>", "QDRANT_MCP_SNAPSHOT_ALLOWED_ORIGINS": "<value>", "FASTEMBED_CACHE_PATH": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: QDRANT_URL, QDRANT_API_KEY, QDRANT_LOCAL_PATH, QDRANT_MCP_TOOLSETS, QDRANT_MCP_READ_ONLY, QDRANT_MCP_MAX_LIMIT, QDRANT_MCP_SNAPSHOT_ALLOWED_ORIGINS, FASTEMBED_CACHE_PATH
Qdrant MCP ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-12 The full Qdrant API as 58 MCP tools: plain-text semantic/BM25/hybrid search and a search advisor.