mcp-qdrant

unofficial MCP server for Qdrant

Qdrant's API as
49 MCP tools.
No embedding step.

The official server hands your client two tools, qdrant-store and qdrant-find, and runs your documents through its own embedding model. This one registers a tool per Qdrant operation and never touches your vectors.

Read the source (opens in a new tab)
Requirements and defaults
requiresQdrant server v1.19.0 or newer
runtimePython 3.12 or newer
default setcore, 13 of the 49 tools
licenceMIT. On PyPI as mcp-qdrant

All 49 tool names

core13
search9
payload12
snapshots9
observability6
Read all 49 in the register

157 tests. Integration tests run against a real qdrant/qdrant:v1.19.0 (opens in a new tab) on every pull request. The 49 tools above are generated (opens in a new tab) from the running registry, and CI fails if this page and the server disagree. See the tests (opens in a new tab)

Two servers, same database. The difference is one box.

Both talk to the same Qdrant over the same HTTP API. Where they differ is what happens between your client and the SDK call.

Diagram: Claude Desktop, Code or claude.ai sends a vector and payload — your vector, from whatever model you already use, passed through and never read — to mcp-qdrant, which validates it with Pydantic and calls the qdrant-client SDK. The SDK talks HTTP to your own Qdrant, v1.19 or newer.

If store and find are all you need, use theirs.

The official server embeds your documents for you, which means it works with no embedding pipeline of your own, and two tool descriptions cost almost nothing in a context window. It is maintained by Qdrant. Everything on this page assumes the opposite trade: that you already have an embedding step you control, and you want the rest of Qdrant's API next to it.

Two tools counted against qdrant/mcp-server-qdrant (opens in a new tab) on 4 September 2026.

Feature comparison between qdrant/mcp-server-qdrant and mcp-qdrant
qdrant/mcp-server-qdrantmcp-qdrant
tools registered249, of which 13 by default
generates embeddingsyes, with fastembedno
collection managementno6 tools
search beyond plain kNNno9 tools
payload and index editingno12 tools
snapshots and restoreno9 tools
server observabilityno6 tools
maintained byQdrantindependent, MIT

What the other 36 are for.

core is 13 tools and it is a complete MCP server on its own. These are the reasons to turn the rest on.

Run hybrid search without writing the fusion yourself.

qdrant_query, qdrant_query_groups, qdrant_query_batch

One call carries several prefetch stages and the RRF or DBSF fusion step. Grouped queries return the best hits per source document instead of per chunk.

Search by example, or steer between examples.

qdrant_recommend, qdrant_discover, qdrant_distance_matrix_pairs

Positive and negative examples instead of a query vector, and a pairwise distance matrix over a sample when you want the shape of the space rather than a ranking.

Fix the data in place instead of re-ingesting it.

qdrant_payload_set, qdrant_payload_index_create, qdrant_payload_facet, qdrant_vectors_update, qdrant_points_batch_update

Add an index to a live collection, count facets over a field, replace vectors by id, or run a batch of point operations atomically in the order given.

Back up before a migration and restore after it goes wrong.

qdrant_snapshot_create, qdrant_snapshot_recover, qdrant_storage_snapshot_create

Per collection or whole storage. The two download tools confirm a snapshot exists and return the URL to fetch it from; they do not transfer the file.

Errors come back as Qdrant's errors. Every call goes through retry-with-backoff and returns Qdrant's own message. Your model reads collection not found, not Error executing tool.

You choose the surface. The default is 13 tools.

Toolsets to register
13 · 8 ro
9 · 9 ro
12 · 1 ro
9 · 4 ro
6 · 4 ro
admin — a valid toolset name that registers nothing. Cluster and shard administration was scoped out.

Every tool description is loaded into your model's context on every conversation. That is why the default is core and not all five. Turn on what the project needs and leave the rest off.

.mcp.json

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

REGISTERED

13of 49

core
search
payload
snapshots
observability

Filled = registered. Red = writes to your data. Hollow = not registered.

13 of 49 tools registered.

Claude Desktop, no JSON

Download mcp-qdrant.mcpb from the latest release (opens in a new tab) and double-click it. Claude Desktop installs the server through uv and asks for the Qdrant URL, API key, local path, toolsets and read-only mode in its own settings form.

No Qdrant yet

shell

QDRANT_LOCAL_PATH=./qdrant_data uvx mcp-qdrant

Runs Qdrant embedded, on disk, in the same process. No server, no Docker, nothing to install beyond uv. QDRANT_URL and QDRANT_LOCAL_PATH are mutually exclusive.

Remote, one fixed Qdrant

shell

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

For claude.ai. The shared secret is required — the server refuses to start as streamable-http without one. In claude.ai: Customize → Connectors → Add custom connector, authentication None, then add a request header Authorization → Bearer <the same secret>.

Remote, bring your own Qdrant

shell

QDRANT_MCP_BYO=1 \
QDRANT_MCP_TRANSPORT=streamable-http \
QDRANT_MCP_HTTP_HOST=0.0.0.0 \
mcp-qdrant

No backing Qdrant of its own; each caller sends theirs. Two request headers: Authorization = your Qdrant URL, sent verbatim with no Bearer prefix, and x-api-key = its API key if it needs one. Your Qdrant must be reachable from the public internet — the SSRF guard rejects private, loopback and link-local addresses.

Docker

shell

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=replace-with-a-long-random-secret \
  ghcr.io/avaazquezz/qdrant-mcp:latest

The image only makes sense with streamable-http; stdio needs a client that owns the process's stdin and stdout. On Linux host.docker.internal does not resolve — add --add-host=host.docker.internal:host-gateway or use your host's LAN address.

All 49, printed.

49 of 49 shown

49 of 49 shown

core13

  • qdrant_health_check

    Confirm the configured Qdrant instance is reachable and responding.

  • qdrant_collection_create

    Create 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_list

    List every collection name in the configured Qdrant instance.

  • qdrant_collection_info

    Return full config and status of one collection.

  • qdrant_collection_update

    Update optimizer/HNSW/collection/vector params on an existing collection.

  • qdrant_collection_delete destructive

    Delete a collection and all its points; a no-op if it doesn't exist.

  • qdrant_collection_exists

    Check whether a collection exists, without raising if it doesn't.

  • qdrant_points_upsert destructive

    Insert or replace points (id + vector + payload) in a collection.

  • qdrant_points_get

    Retrieve points by id; unknown ids are simply omitted, not an error.

  • qdrant_points_delete destructive

    Delete points by id list or by payload filter — exactly one of the two.

  • qdrant_points_scroll

    Page through all points in a collection, optionally filtered.

  • qdrant_points_count

    Count points in a collection, optionally matching a filter.

  • qdrant_query

    Vector similarity search, with optional hybrid search over multiple prefetch stages.

search9

  • qdrant_query_batch

    Run 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_groups

    Vector 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_recommend

    Find 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_batch

    Run multiple independent recommend queries against one collection in a single round trip.

  • qdrant_recommend_groups

    Recommend query grouped by a payload field, up to `group_size` hits per group.

  • qdrant_discover

    Rank 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_batch

    Run multiple independent discover queries against one collection in a single round trip.

  • qdrant_distance_matrix_pairs

    Pairwise 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_offsets

    Same 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.

payload12

  • qdrant_payload_set

    Merge 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_overwrite destructive

    Replace 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_delete destructive

    Delete specific payload keys from selected points — exactly one of `ids`/`points_filter`. Other keys are untouched.

  • qdrant_payload_clear destructive

    Wipe the entire payload of selected points, keeping their vectors — exactly one of `ids`/`points_filter`.

  • qdrant_payload_facet

    Count 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_create

    Create 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_delete destructive

    Delete the payload index on `field_name`.

  • qdrant_collection_vector_create

    Add a new named vector (dense or sparse) to a collection that already has points, without touching them.

  • qdrant_collection_vector_delete destructive

    Remove 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_update destructive

    Run 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_update destructive

    Replace 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_delete destructive

    Remove specific named vectors from selected points, keeping their payload and other vectors — exactly one of `ids`/`points_filter`.

snapshots9

  • qdrant_snapshot_create

    Create a snapshot of one collection's current state.

  • qdrant_snapshot_list

    List the snapshots stored for one collection.

  • qdrant_snapshot_delete destructive

    Delete a collection snapshot, freeing its disk space on the server — does not touch the live collection.

  • qdrant_snapshot_recover destructive

    Overwrite `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_download

    Confirm 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_create

    Create a snapshot of the whole storage (every collection and server config), not just one collection.

  • qdrant_storage_snapshot_list

    List the full-storage snapshots stored on the server.

  • qdrant_storage_snapshot_delete destructive

    Delete a full-storage snapshot, freeing its disk space.

  • qdrant_storage_snapshot_download

    Confirm 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.

observability6

  • qdrant_telemetry

    Server-wide telemetry: build info, per-collection stats, request counters, memory and hardware usage. Not tied to any one collection.

  • qdrant_metrics_prometheus

    Return 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_get

    Current server-wide resource quotas (memory/disk limits) and actual usage.

  • qdrant_quotas_set

    Update server-wide resource quotas. Only the fields you pass are changed; omitted ones keep their current value.

  • qdrant_issues_list

    List 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_clear destructive

    Clear all accumulated issues.

Generated from the running tool registry by scripts/gen_tools_json.py (opens in a new tab). CI fails if this page and the server disagree.

The things that would stop me installing this.

Do I need a Qdrant already running?

No. Set QDRANT_LOCAL_PATH to a directory and the qdrant-client SDK runs Qdrant embedded, on disk, in the same process — no server, no Docker. QDRANT_URL and QDRANT_LOCAL_PATH are mutually exclusive; if you set neither, the SDK falls back to its own default of localhost:6333.

What breaks on a Qdrant older than 1.19?

Two payload tools, qdrant_collection_vector_create and qdrant_collection_vector_delete, hit an endpoint that returns 404 on older servers — verified against v1.13.6 and v1.15.1. Everything else works. v1.19.0 is the only version this project tests against.

Can I stop it writing to my production data?

QDRANT_MCP_READ_ONLY=1 removes every tool that is not marked read-only from the registry itself. 26 tools remain, 23 are gone, and a client calling tools/list never sees them. There is no permission check to get past, because there is no code path left.

Is 49 tools going to fill my context window?

The default is core: 13 tools. Toolsets are opt-in through QDRANT_MCP_TOOLSETS, and admin is a valid name that registers nothing. Build the surface you want in the panel above and copy the config it produces.

Is this Qdrant's project?

No. It is independent, MIT-licensed, and not affiliated with or endorsed by Qdrant. It wraps Qdrant's own qdrant-client SDK and reuses that SDK's Pydantic models for tool input, so the schemas track the SDK version instead of a hand-maintained copy.

Is it really the whole API?

Not quite, and the gap is deliberate: collection aliases and cluster/shard administration are not exposed. Real resharding only exists on Qdrant Cloud and the rest only matters for a distributed deployment. Everything under collections, points, search, payload, indexing, snapshots and observability is here — 49 tools.