Qdrant MCP

Qdrant MCP

[PyPI version] [CI] [Python versions] [License: MIT]

[Qdrant MCP server]

A Model Context Protocol (MCP) server that exposes the full Qdrant vector database API as tools — collection management, advanced hybrid search, payload and vector editing, snapshots, and server observability. Not just store/find.

Table of Contents

• Overview
• Key Features
• Requirements
• Installation
  • PyPI
  • Docker
  • Claude Desktop bundle (.mcpb)
• Quick Start
• Connecting to Claude
  • Claude Desktop / Claude Code (local, stdio)
  • Remote (streamable-http)
• Text Search
• Prompts
• Configuration Reference
• Available Tools
• Read-Only Mode
• Architecture
• Security
• Development
• Versioning & Changelog
• License

Overview

Qdrant 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 parses documents and never decides how to chunk text — it is not a RAG pipeline, on purpose. A client can bring its own vectors, or — with the optional embeddings extra — send plain text and search by meaning or by keywords (see Text Search).

That is what sets it apart from the official Qdrant MCP server, which exposes exactly two tools (store/find). 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, and query it in plain text too.

See ROADMAP.md for the full phase-by-phase design history, including every finding that shaped a decision (in Spanish).

Key Features

• Text search — semantic search with plain text (query_text, embedded locally with fastembed using the model the collection declares), BM25 keyword search with stemming and stopwords (bm25_query, Qdrant 1.20, no embeddings needed), and both fused in one hybrid query. Upserts accept text too. Works on collections built elsewhere once their model is declared.
• Full collection & point lifecycle — create/update/delete collections, CRUD on points, scrolling, counting.
• Every Qdrant search mode — plain vector search over dense, sparse and multivectors, hybrid search (RRF — optionally weighted — and DBSF fusion), nested multi-stage prefetch (fuse dense+sparse, then rerank with a multivector), MMR diversity, custom score formulas (payload boosts, recency and geo decay), ordering by a payload field, random sampling, grouped queries, recommend, discover, and pairwise distance matrices. Search accuracy knobs (search_params, score_threshold, paging, timeouts) are accepted by every search tool.
• Payload & vector editing — set/overwrite/delete/clear payload, payload indexes, facet counting, named (dense/sparse) vector management, ordered batch operations.
• Snapshots — per-collection and full-storage backup/restore.
• A search advisor — qdrant_collection_doctor checks a collection (status, index, memory, aliases, text setup) and answers each finding with the exact tool call that fixes it; qdrant_search_quality_eval measures recall@k of the approximate search against an exact one, and latency, for any search_params variants — so tuning HNSW or quantization is judged by numbers, e.g. "quantized without rescoring: recall 0.97; with rescoring: 1.0".
• Guided workflows — MCP prompts that walk a model through a whole task: tune a collection's search (diagnose, measure, propose, wait for approval), rebuild a collection without downtime, or add text search to an existing collection. In Claude Code they're slash commands, e.g. /mcp__qdrant__tune_search docs. The server also hands the model a short orientation (its MCP instructions), built from the toolsets you enabled.
• Aliases, reindexing & introspection — switch the collection a name points to without downtime, copy points between collections server-side (vectors never pass through the model), check shard layout and whether the optimizer has finished indexing, and profile the payload keys a collection actually has before writing a filter.
• Observability — telemetry, Prometheus metrics endpoint, resource quotas, self-diagnosed issues.
• Opt-in tool surface — the 58 tools are grouped into toolsets you enable explicitly, so a client isn't handed all of them by default (only the 13-tool core toolset is on).
• Read-only guard — one flag removes every mutating tool from the registry entirely.
• Easy on the model's context — the schemas the server advertises are compact (Qdrant's verbose Filter and configuration models are summarized, validation unchanged), so the default toolset costs ~47 KB of schema instead of ~150 KB; with_payload can name just the keys to return (["title", "url"]), since payload is most of what a model reads back; and a per-call result cap (QDRANT_MCP_MAX_LIMIT) stops one mistaken limit from flooding the conversation.
• Resilient by default — every Qdrant call goes through retry-with-backoff and returns Qdrant's own error message on failure, never a generic exception.

Requirements

• Python 3.12+
• Qdrant server v1.19.0 or newer; tested against v1.20.0. Two tools (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. Tool descriptions state the behavior verified on v1.20.0, and say so where v1.19 differed (alias batches, MMR with offset). Text search needs v1.16+ (it keeps the model in the collection's metadata), and its BM25 mode v1.20+.

Installation

PyPI

# Run without installing (recommended for Claude Desktop/Code configs)uvx mcp-qdrant
# Or install into your environmentpip install mcp-qdrant
# With text search (adds fastembed; models are downloaded on first use)uvx --from 'mcp-qdrant[embeddings]' 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> \  -v mcp-qdrant-models:/models \  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.

Claude Desktop bundle (.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.

Quick Start

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:

1. qdrant_health_check — confirms the configured Qdrant instance is reachable before doing anything else.
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}.

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.

Connecting to Claude

Claude Desktop / Claude Code (local, 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.

Remote (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.)

Text Search

Text search needs no extra configuration — the collection carries it. Its metadata records which model made each dense vector and which payload field holds the text, so every later query and upsert uses the same model (a query embedded with a different model would return plausible-looking nonsense with no error):

{"mcp_qdrant": {"text_field": "text", "models": {"dense": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"}}}

• New collection — qdrant_collection_create with text_model (creates a dense vector of the model's size and records it) and/or text_language (adds a BM25 index on the text field: stemmed, accent-folded, stopwords removed).
• Existing collection — qdrant_collection_update with text_models ({"<vector>": "<model>"}, "" for the unnamed vector) declares the model its vectors were made with; the size is checked against the vector. For BM25, create a text payload index with "scoring": true (and a stemmer) on the text field with qdrant_payload_index_create.
• Write — qdrant_points_upsert with {"id": 1, "text": "..."} instead of a vector: one text is one point, nothing is split.
• Query — qdrant_query with query_text (semantic), bm25_query (keywords), or both as prefetch stages fused with "rrf" (hybrid).

Guard rails: a text longer than the model reads (128 tokens, ~500 characters, for the multilingual MiniLM) is refused instead of silently cut — split it into several points; models that need query/document prefixes (e5, nomic, ...) aren't offered, since fastembed doesn't add them; a collection with points won't switch a vector to a different model (null in text_models removes a wrong declaration first); and text into a collection whose vectors have no declared model is refused rather than stored without a vector. BM25 with a language needs a Qdrant server — the embedded local mode only ranks default-tokenized indexes.

Semantic search needs the embeddings extra (the Docker image and the .mcpb bundle include it); BM25 needs Qdrant 1.20 but no extra. Models are downloaded on first use into FASTEMBED_CACHE_PATH — set it to a persistent directory (the Docker image uses /models, so mount a volume there) to download once.

Prompts

Guided workflows the user starts; each is offered only when the tools it uses are enabled and the server isn't read-only. In Claude Code they're slash commands with positional arguments.

Example: /mcp__qdrant__tune_search docs.

Configuration Reference

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.

Available Tools

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, 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), and the advisor: a collection doctor and a search-quality evaluation. 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).

Read-Only Mode

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.

Architecture

• Single shared client. One AsyncQdrantClient is built once at startup and closed over by every tool.
• One registration choke point. Every tool module calls into a single 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.
• Resilience. Every Qdrant call is wrapped with 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.

Security

• Mandatory authentication for 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. The bearer token is compared in constant time.
• No server-side request forgery through snapshot restores. qdrant_snapshot_recover makes the Qdrant server itself fetch location, so it only accepts file:// paths, QDRANT_URL's own origin and the origins listed in QDRANT_MCP_SNAPSHOT_ALLOWED_ORIGINS — not, say, a cloud metadata endpoint on your internal network.
• No blind retries of writes. A call is retried only when the request never reached Qdrant (connection refused, connect timeout). A timeout after sending is reported as "may have been applied" instead of being repeated, so a slow write can't run twice.
• Input validation everywhere. Every tool's input is a Pydantic model — malformed input is rejected with a structured error before it reaches the Qdrant SDK.
• Read-only guard. QDRANT_MCP_READ_ONLY removes every mutating tool from the registry — see Read-Only Mode.

Development

git clone https://github.com/avaazquezz/Qdrant-MCP.gitcd Qdrant-MCPuv sync --dev --extra embeddingsuv run pre-commit install

uv run ruff check .            # lintuv run ruff format --check .   # formattinguv run mypy .                  # type checking (strict)uv run pytest                  # unit testsuv 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          # regenerateuv run python scripts/gen_tools_doc.py --check  # verify, no changes (what CI runs)

Versioning & Changelog

This project follows Semantic Versioning. See CHANGELOG.md for release notes and ROADMAP.md for the phased design history behind each version.

License

MIT