++++

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-qdrant
View on GitHub →
verified —PyPI versionCI statusPython versionsLicense: MIT — built on the official qdrant-client sdk

the surface

official qdrant-mcp-server · 2 tools

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

[control]

Full control, not a shim

Complete collection & point lifecycle plus every Qdrant search mode — hybrid, grouped, recommend, discover, distance matrices.

[safety]

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.

[deploy]

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.

[observability]

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.

session.log

{ "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_check
    read-onlyidempotent

    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
    read-onlyidempotent

    List every collection name in the configured Qdrant instance.

  • qdrant_collection_info
    read-onlyidempotent

    Return full config and status of one collection.

  • qdrant_collection_update
    idempotent

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

  • qdrant_collection_delete
    destructiveidempotent

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

  • qdrant_collection_exists
    read-onlyidempotent

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

  • qdrant_points_upsert
    destructiveidempotent

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

  • qdrant_points_get
    read-onlyidempotent

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

  • qdrant_points_delete
    destructiveidempotent

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

  • qdrant_points_scroll
    read-onlyidempotent

    Page through all points in a collection, optionally filtered.

  • qdrant_points_count
    read-onlyidempotent

    Count points in a collection, optionally matching a filter.

  • qdrant_query
    read-onlyidempotent

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

  • qdrant_query_batch
    read-onlyidempotent

    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
    read-onlyidempotent

    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
    read-onlyidempotent

    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
    read-onlyidempotent

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

  • qdrant_recommend_groups
    read-onlyidempotent

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

  • qdrant_discover
    read-onlyidempotent

    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
    read-onlyidempotent

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

  • qdrant_distance_matrix_pairs
    read-onlyidempotent

    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
    read-onlyidempotent

    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.

  • qdrant_payload_set
    idempotent

    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
    destructiveidempotent

    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
    destructiveidempotent

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

  • qdrant_payload_clear
    destructiveidempotent

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

  • qdrant_payload_facet
    read-onlyidempotent

    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
    idempotent

    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
    destructiveidempotent

    Delete the payload index on `field_name`.

  • qdrant_collection_vector_create
    idempotent

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

  • qdrant_collection_vector_delete
    destructiveidempotent

    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
    destructiveidempotent

    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
    destructiveidempotent

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

  • qdrant_snapshot_create

    Create a snapshot of one collection's current state.

  • qdrant_snapshot_list
    read-onlyidempotent

    List the snapshots stored for one collection.

  • qdrant_snapshot_delete
    destructiveidempotent

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

  • qdrant_snapshot_recover
    destructiveidempotent

    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
    read-onlyidempotent

    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
    read-onlyidempotent

    List the full-storage snapshots stored on the server.

  • qdrant_storage_snapshot_delete
    destructiveidempotent

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

  • qdrant_storage_snapshot_download
    read-onlyidempotent

    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.

  • qdrant_telemetry
    read-onlyidempotent

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

  • qdrant_metrics_prometheus
    read-onlyidempotent

    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
    read-onlyidempotent

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

  • qdrant_quotas_set
    idempotent

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

  • qdrant_issues_list
    read-onlyidempotent

    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
    destructiveidempotent

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

01

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/storage
02

Point 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"
      }
    }
  }
}
03

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.

nearest neighbor: you

Point your MCP client at your Qdrant.

uvx mcp-qdrant
View on GitHub