Qdrant-MCP

MCP server that wraps the Qdrant vector database API as tools. See ROADMAP.md.

Tools

Generated from the live tool registry — run uv run python scripts/gen_tools_doc.py after adding or changing a tool.

Tool Toolset Read-only Destructive Idempotent Description
qdrant_health_check core ✅ ❌ ✅ Confirm the configured Qdrant instance is reachable and responding.
qdrant_collection_create core ❌ ❌ ❌ 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.
qdrant_collection_list core ✅ ❌ ✅ List every collection name in the configured Qdrant instance.
qdrant_collection_info core ✅ ❌ ✅ Return full config and status of one collection.
qdrant_collection_update core ❌ ❌ ✅ Update optimizer/HNSW/collection/vector params on an existing collection.
qdrant_collection_delete core ❌ ✅ ✅ Delete a collection and all its points; a no-op if it doesn't exist.
qdrant_collection_exists core ✅ ❌ ✅ Check whether a collection exists, without raising if it doesn't.
qdrant_points_upsert core ❌ ✅ ✅ Insert or replace points (id + vector + payload) in a collection.
qdrant_points_get core ✅ ❌ ✅ Retrieve points by id; unknown ids are simply omitted, not an error.
qdrant_points_delete core ❌ ✅ ✅ Delete points by id list or by payload filter — exactly one of the two.
qdrant_points_scroll core ✅ ❌ ✅ Page through all points in a collection, optionally filtered.
qdrant_points_count core ✅ ❌ ✅ Count points in a collection, optionally matching a filter.
qdrant_query core ✅ ❌ ✅ Vector similarity search, with optional hybrid search over multiple prefetch stages.
qdrant_query_batch search ✅ ❌ ✅ 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 search ✅ ❌ ✅ Vector query grouped by a payload field, up to group_size hits per group — e.g. the best-matching chunks per source document.
qdrant_recommend search ✅ ❌ ✅ 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.
qdrant_recommend_batch search ✅ ❌ ✅ Run multiple independent recommend queries against one collection in a single round trip.
qdrant_recommend_groups search ✅ ❌ ✅ Recommend query grouped by a payload field, up to group_size hits per group.
qdrant_discover search ✅ ❌ ✅ 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 search ✅ ❌ ✅ Run multiple independent discover queries against one collection in a single round trip.
qdrant_distance_matrix_pairs search ✅ ❌ ✅ 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 search ✅ ❌ ✅ 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 payload ❌ ❌ ✅ Merge fields into the payload of selected points — exactly one of ids/points_filter.
qdrant_payload_overwrite payload ❌ ✅ ✅ Replace the entire payload of selected points with payload — exactly one of ids/points_filter.
qdrant_payload_delete payload ❌ ✅ ✅ Delete specific payload keys from selected points — exactly one of ids/points_filter.
qdrant_payload_clear payload ❌ ✅ ✅ Wipe the entire payload of selected points, keeping their vectors — exactly one of ids/points_filter.
qdrant_payload_facet payload ✅ ❌ ✅ Count distinct values of a payload field across the collection (or a filtered subset) — e.g. how many points per city.
qdrant_payload_index_create payload ❌ ❌ ✅ Create a payload index on field_name, speeding up filters that use it.
qdrant_payload_index_delete payload ❌ ✅ ✅ Delete the payload index on field_name.
qdrant_collection_vector_create payload ❌ ❌ ✅ Add a new named vector (dense or sparse) to a collection that already has points, without touching them.
qdrant_collection_vector_delete payload ❌ ✅ ✅ Remove a named vector (dense or sparse) from a collection — points keep their other vectors and payload.
qdrant_points_batch_update payload ❌ ✅ ❌ Run multiple point operations (upsert, delete, set/overwrite/delete/clear payload, update/delete vectors) atomically against one collection, in the order given.
qdrant_vectors_update payload ❌ ✅ ✅ Replace the vector(s) of existing points by id — leaves their payload untouched.
qdrant_vectors_delete payload ❌ ✅ ✅ Remove specific named vectors from selected points, keeping their payload and other vectors — exactly one of ids/points_filter.
qdrant_snapshot_create snapshots ❌ ❌ ❌ Create a snapshot of one collection's current state.
qdrant_snapshot_list snapshots ✅ ❌ ✅ List the snapshots stored for one collection.
qdrant_snapshot_delete snapshots ❌ ✅ ✅ Delete a collection snapshot, freeing its disk space on the server — does not touch the live collection.
qdrant_snapshot_recover snapshots ❌ ✅ ✅ Overwrite collection_name with the state captured in a snapshot — everything written since that snapshot is lost.
qdrant_snapshot_download snapshots ✅ ❌ ✅ 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 snapshots ❌ ❌ ❌ Create a snapshot of the whole storage (every collection and server config), not just one collection.
qdrant_storage_snapshot_list snapshots ✅ ❌ ✅ List the full-storage snapshots stored on the server.
qdrant_storage_snapshot_delete snapshots ❌ ✅ ✅ Delete a full-storage snapshot, freeing its disk space.
qdrant_storage_snapshot_download snapshots ✅ ❌ ✅ 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 observability ✅ ❌ ✅ Server-wide telemetry: build info, per-collection stats, request counters, memory and hardware usage.
qdrant_metrics_prometheus observability ✅ ❌ ✅ 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 observability ✅ ❌ ✅ Current server-wide resource quotas (memory/disk limits) and actual usage.
qdrant_quotas_set observability ❌ ❌ ✅ Update server-wide resource quotas.
qdrant_issues_list observability ✅ ❌ ✅ List the issues Qdrant has detected about its own configuration (e.g. a heavily-filtered field with no payload index).
qdrant_issues_clear observability ❌ ✅ ✅ Clear all accumulated issues.

Configuration

Environment variables: QDRANT_URL, QDRANT_API_KEY, QDRANT_LOCAL_PATH (exactly one of QDRANT_URL/QDRANT_LOCAL_PATH), QDRANT_MCP_READ_ONLY, QDRANT_MCP_TRANSPORT (stdio default, or streamable-http), QDRANT_MCP_TOOLSETS (comma-separated; default core only — opt in to search, payload, snapshots, observability explicitly), QDRANT_MCP_BYO (see below — mutually exclusive with QDRANT_URL/QDRANT_LOCAL_PATH).

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 double-click the .mcpb bundle attached to a release — Claude Desktop prompts for the same settings through its own UI, no JSON to edit.

Remote (streamable-http) — e.g. a custom connector in Claude.ai

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

Public "bring your own Qdrant" instance (QDRANT_MCP_BYO)

A streamable-http deployment can run with no backing Qdrant of its own — every caller supplies their own Qdrant instance (their own Qdrant Cloud account, their company's self-hosted Qdrant, whatever) per request, instead of using one the operator hosts and pays for. Isolation between callers is automatic — each one talks to their own database — so there's no shared secret, no per-user account, and no data at rest on this server.

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

Two request headers, reused for a different purpose than their name suggests — verified hands-on that Claude.ai's custom-connector "Request headers" UI rejects made-up header names outright unless Anthropic has approved them, so this reuses two pre-approved ones instead of inventing X-Qdrant-Url/X-Qdrant-Api-Key:

  • Authorization (required) — your Qdrant URL, e.g. https://xyz.cloud.qdrant.io:6333. Sent verbatim, no Bearer prefix needed.
  • x-api-key (optional) — your Qdrant API key, if your instance needs one.

In Claude.ai: Add custom connector → authentication "None" → add both as Request headers. Your Qdrant must be reachable from the public internet — an SSRF guard rejects any URL that resolves to a private/internal/loopback address.

Project links

Data verified by PyPI on Aug 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.1.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for adrivaazz from gravatar.com adrivaazz

Credits

Author: Adrián

GitHub Statistics

Data verified by PyPI on Aug 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License Copyright (c) 2026 Adrián Permission is hereby granted, free of charge, to any person ...)

Requires

Python >=3.12

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcp_qdrant-1.1.0.tar.gz (30.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mcp_qdrant-1.1.0-py3-none-any.whl (42.3 kB view details)

Uploaded Python 3

File details

Details for the file mcp_qdrant-1.1.0.tar.gz.

File metadata

  • Download URL: mcp_qdrant-1.1.0.tar.gz
  • Upload date:
  • Size: 30.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for mcp_qdrant-1.1.0.tar.gz
Algorithm Hash digest
SHA256 6b686d4d93131527afafbaeb9542955108863132942012ef486fa30642249636
MD5 5fedfa4c91c9363d2aa12103f3f02fba
BLAKE2b-256 3d7fcf606229dc077ac271f583e34c14de5fcfd67e11a0945c5fff07814729e9

See more details on using hashes here.

File details

Details for the file mcp_qdrant-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: mcp_qdrant-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 42.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for mcp_qdrant-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 bced65bc4c9ad15d61461dedf375c56b646ce2889245bc4fabd8900e25901ce1
MD5 ad17416f0da8a938179741351c5d7fe0
BLAKE2b-256 3769257dd1b31e16820dbbc9d8c76e6d6aa6760960eb22decfcac15b58b6e6f4

See more details on using hashes here.

Release history Release notifications | RSS feed

1.1.1

2 files

This release

1.1.0 This release

2 files

1.0.1

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page