model context protocol · vector search
Qdrant MCP
The full Qdrant API as MCP tools — collections, every search mode, payload, snapshots, observability. Not just store/find.
uvx mcp-qdrantthe surface
49
tools, not two
Every collection, point, search, payload, snapshot, and observability operation Qdrant exposes. You bring your own vectors — it never embeds anything for you.
your llm client──▶qdrant mcp — thin wrapper──▶your qdrant
No embeddings generated, no chunking, no vector opinions — it's not a RAG system, on purpose. Whatever your client wants to store or query, it brings its own vectors.
why this one
Full control, not a shim
Complete collection & point lifecycle plus every Qdrant search mode — hybrid, grouped, recommend, discover, distance matrices.
Production-grade safety
A read-only guard removes every mutating tool from the registry, Pydantic validates every input, and BYO mode re-resolves DNS on each request to defeat SSRF.
Runs how you need it
PyPI, Docker, or the Claude Desktop .mcpb bundle. Toolsets are opt-in, and bring-your-own-Qdrant mode needs no database of its own.
Observable
Telemetry, Prometheus metrics, resource quotas, and self-diagnosed issues — know what your Qdrant deployment is doing, not flying blind.
see it run
A real client session
Health check, create a collection, upsert, query.
{ "ok": true }
{ "status": "ok" }
{ "status": "ok" }
{ "results": [{ "id": 1, "score": 1.0, "payload": { "title": "hello" } }] }
every tool
Generated, not hand-written
Straight from the live tool registry.
qdrant_health_checkread-onlyidempotentConfirm the configured Qdrant instance is reachable and responding.
qdrant_collection_createCreate a collection: either a single unnamed vector (`vector_size` + `distance`), or one or more named vectors (`vectors`, each a full `VectorParams` — size, distance, and optionally its own `multivector_config` for ColBERT-style multi-vectors or `quantization_config`) — exactly one of the two. `sparse_vectors` defines sparse (keyword-style) vectors at creation time. `quantization_config` (scalar/product/binary) and `strict_mode_config` apply to the whole collection.
qdrant_collection_listread-onlyidempotentList every collection name in the configured Qdrant instance.
qdrant_collection_inforead-onlyidempotentReturn full config and status of one collection.
qdrant_collection_updateidempotentUpdate optimizer/HNSW/collection/vector params on an existing collection.
qdrant_collection_deletedestructiveidempotentDelete a collection and all its points; a no-op if it doesn't exist.
qdrant_collection_existsread-onlyidempotentCheck whether a collection exists, without raising if it doesn't.
qdrant_points_upsertdestructiveidempotentInsert or replace points (id + vector + payload) in a collection.
qdrant_points_getread-onlyidempotentRetrieve points by id; unknown ids are simply omitted, not an error.
qdrant_points_deletedestructiveidempotentDelete points by id list or by payload filter — exactly one of the two.
qdrant_points_scrollread-onlyidempotentPage through all points in a collection, optionally filtered.
qdrant_points_countread-onlyidempotentCount points in a collection, optionally matching a filter.
qdrant_queryread-onlyidempotentVector similarity search, with optional hybrid search over multiple prefetch stages.
qdrant_query_batchread-onlyidempotentRun multiple independent queries against one collection in a single round trip — same query shapes as `qdrant_query` (plain vector or fusion+prefetch hybrid search), one per list item.
qdrant_query_groupsread-onlyidempotentVector query grouped by a payload field, up to `group_size` hits per group — e.g. the best-matching chunks per source document. Same query shapes as `qdrant_query`.
qdrant_recommendread-onlyidempotentFind points similar to a set of positive examples and dissimilar to a set of negative ones (vectors or point ids) — Qdrant's recommendation API. Requires at least one of `positive`/`negative`; the server rejects an empty request with a clear error.
qdrant_recommend_batchread-onlyidempotentRun multiple independent recommend queries against one collection in a single round trip.
qdrant_recommend_groupsread-onlyidempotentRecommend query grouped by a payload field, up to `group_size` hits per group.
qdrant_discoverread-onlyidempotentRank points by how well they fit a target within positive/negative context pairs (vectors or point ids) — Qdrant's discovery search, a finer-grained alternative to recommend.
qdrant_discover_batchread-onlyidempotentRun multiple independent discover queries against one collection in a single round trip.
qdrant_distance_matrix_pairsread-onlyidempotentPairwise distance matrix between a random sample of points: for each of `sample` points, its `limit` closest neighbors among that same sample — returned as a flat list of (a, b, score) pairs.
qdrant_distance_matrix_offsetsread-onlyidempotentSame distance matrix as `qdrant_distance_matrix_pairs`, in a column-oriented shape (offsets into a shared id list + a parallel score array) — more compact for large samples.
qdrant_payload_setidempotentMerge fields into the payload of selected points — exactly one of `ids`/`points_filter`. Existing keys not in `payload` are kept. `key` sets a nested sub-field (e.g. `"metadata.author"`) instead of merging at the payload root.
qdrant_payload_overwritedestructiveidempotentReplace the entire payload of selected points with `payload` — exactly one of `ids`/`points_filter`. Unlike `qdrant_payload_set`, existing keys not in `payload` are dropped.
qdrant_payload_deletedestructiveidempotentDelete specific payload keys from selected points — exactly one of `ids`/`points_filter`. Other keys are untouched.
qdrant_payload_cleardestructiveidempotentWipe the entire payload of selected points, keeping their vectors — exactly one of `ids`/`points_filter`.
qdrant_payload_facetread-onlyidempotentCount distinct values of a payload field across the collection (or a filtered subset) — e.g. how many points per `city`. `exact` trades speed for an exact count instead of an approximation.
qdrant_payload_index_createidempotentCreate a payload index on `field_name`, speeding up filters that use it. `field_schema` can be a simple type name ("keyword", "integer", "float", "geo", "text", "bool", "datetime", "uuid") or a detailed params object (e.g. a `text` index with a specific tokenizer, or a `keyword` index marked `is_tenant`).
qdrant_payload_index_deletedestructiveidempotentDelete the payload index on `field_name`.
qdrant_collection_vector_createidempotentAdd a new named vector (dense or sparse) to a collection that already has points, without touching them.
qdrant_collection_vector_deletedestructiveidempotentRemove a named vector (dense or sparse) from a collection — points keep their other vectors and payload. Same server-version requirement as `qdrant_collection_vector_create`.
qdrant_points_batch_updatedestructiveRun multiple point operations (upsert, delete, set/overwrite/delete/clear payload, update/delete vectors) atomically against one collection, in the order given. Each item is one of Qdrant's own tagged operation shapes, keyed by operation name.
qdrant_vectors_updatedestructiveidempotentReplace the vector(s) of existing points by id — leaves their payload untouched. For a named-vector collection, `vector` is a dict keyed by vector name; for a single unnamed vector, pass a plain vector.
qdrant_vectors_deletedestructiveidempotentRemove specific named vectors from selected points, keeping their payload and other vectors — exactly one of `ids`/`points_filter`.
qdrant_snapshot_createCreate a snapshot of one collection's current state.
qdrant_snapshot_listread-onlyidempotentList the snapshots stored for one collection.
qdrant_snapshot_deletedestructiveidempotentDelete a collection snapshot, freeing its disk space on the server — does not touch the live collection.
qdrant_snapshot_recoverdestructiveidempotentOverwrite `collection_name` with the state captured in a snapshot — everything written since that snapshot is lost. Creates the collection if it doesn't exist.
qdrant_snapshot_downloadread-onlyidempotentConfirm a collection snapshot exists and return where to fetch it from — this tool does not transfer the (potentially huge) snapshot file itself; download it yourself (e.g. `curl`) from the returned `url`.
qdrant_storage_snapshot_createCreate a snapshot of the whole storage (every collection and server config), not just one collection.
qdrant_storage_snapshot_listread-onlyidempotentList the full-storage snapshots stored on the server.
qdrant_storage_snapshot_deletedestructiveidempotentDelete a full-storage snapshot, freeing its disk space.
qdrant_storage_snapshot_downloadread-onlyidempotentConfirm a full-storage snapshot exists and return where to fetch it from — same caveat as `qdrant_snapshot_download`: this tool does not transfer the file itself.
qdrant_telemetryread-onlyidempotentServer-wide telemetry: build info, per-collection stats, request counters, memory and hardware usage. Not tied to any one collection.
qdrant_metrics_prometheusread-onlyidempotentReturn the URL where Qdrant serves Prometheus-format metrics — this tool does not fetch the metrics themselves (they're plain text, not JSON); point your Prometheus scraper at the returned `url` instead.
qdrant_quotas_getread-onlyidempotentCurrent server-wide resource quotas (memory/disk limits) and actual usage.
qdrant_quotas_setidempotentUpdate server-wide resource quotas. Only the fields you pass are changed; omitted ones keep their current value.
qdrant_issues_listread-onlyidempotentList the issues Qdrant has detected about its own configuration (e.g. a heavily-filtered field with no payload index). **API Beta** in Qdrant itself — the exact shape can change without notice, so this is returned as-is rather than forced into a fixed schema.
qdrant_issues_cleardestructiveidempotentClear all accumulated issues.
quick install
PyPI (recommended)
uvx mcp-qdrant
pip
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
claude_desktop_config.json / .mcp.json
{
"mcpServers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-qdrant"],
"env": {
"QDRANT_URL": "http://localhost:6333",
"QDRANT_MCP_TOOLSETS": "core,search"
}
}
}
}connect your own qdrant
Self-hosted, on your own server
The full path — Docker Compose for Qdrant, Claude Code over stdio, claude.ai over BYO mode.
Run your own Qdrant
docker compose up on your server. The API key is Qdrant's own auth — nothing to do with this MCP server yet.
docker-compose.yml
services:
qdrant:
image: qdrant/qdrant:latest
restart: unless-stopped
environment:
QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY}
volumes:
- ./qdrant_storage:/qdrant/storagePoint Claude Code at it
Local/stdio — the simplest path. Works as long as Claude Code can reach your Qdrant URL directly.
.mcp.json
{
"mcpServers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-qdrant"],
"env": {
"QDRANT_URL": "https://your-qdrant.example.com:6333",
"QDRANT_API_KEY": "${QDRANT_API_KEY}",
"QDRANT_MCP_TOOLSETS": "core,search"
}
}
}
}Connect claude.ai
claude.ai only reaches remote servers — deploy this MCP once in QDRANT_MCP_BYO=1 mode, then add a custom connector with authentication None and two request headers:
Authorization
https://your-qdrant.example.com:6333
Your Qdrant URL — sent as-is, no Bearer prefix.
x-api-key
your QDRANT_API_KEY
Only needed if your instance requires one.
Your Qdrant must be reachable over public HTTPS for this path — the SSRF guard rejects private/internal addresses.
and if —
FAQ
The official server (qdrant/mcp-server-qdrant) exposes two tools — store and find — and generates embeddings for you. This server covers the rest of Qdrant's surface: collections, points, every search mode, payload, indexing, snapshots, and observability. It never embeds anything.