io.github.avaazquezz/mcp-qdrant
This MCP server exposes the full Qdrant vector database API as MCP tools, letting an LLM client manage collections and points, run advanced searches, and operate a Qdrant deployment end to end.
Create, inspect, update, delete, and check collections, including named/dense/sparse vectors, quantization, HNSW, and text-collection setup.
Perform point CRUD: upsert (with vectors or plain text), get by id, delete by id or filter, scroll with paging/ordering, count, and ordered batch operations.
Search with the unified Query API: vector similarity, semantic
query_text, BM25 keyword search, hybrid fusion (RRF/DBSF), nested prefetch/reranking, MMR diversity, custom score formulas, payload ordering, random sampling, grouped queries, recommend, discover, and distance matrices.Manage payloads and indexes: set/overwrite/delete/clear payload, facet counting, create/delete payload indexes, and manage named dense/sparse vectors.
Back up and restore with collection and full-storage snapshots (create/list/delete/recover/download).
Use admin tooling: aliases for zero-downtime reindexing, shard/optimizer introspection, server-side collection copy, payload schema inference, a collection doctor, and search-quality/recall evaluation.
Monitor the server with telemetry, Prometheus metrics URL, resource quotas, and Qdrant issue reporting/clearing.
Guide workflows via prompts like
tune_search,zero_downtime_reindex, andtext_search_setup, with read-only mode and opt-in toolsets controlling what the model can see and do.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.avaazquezz/mcp-qdrant find similar documents to 'MCP server setup' in the docs collection"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Qdrant MCP
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
Related MCP server: Qdrant MCP Server
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 accepttexttoo. 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_doctorchecks a collection (status, index, memory, aliases, text setup) and answers each finding with the exact tool call that fixes it;qdrant_search_quality_evalmeasures recall@k of the approximate search against an exact one, and latency, for anysearch_paramsvariants — 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 MCPinstructions), 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
coretoolset 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
Filterand configuration models are summarized, validation unchanged), so the default toolset costs ~47 KB of schema instead of ~150 KB;with_payloadcan 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 mistakenlimitfrom 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 returns404on 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 withoffset). 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 environment
pip install mcp-qdrant
# With text search (adds fastembed; models are downloaded on first use)
uvx --from 'mcp-qdrant[embeddings]' mcp-qdrantDocker
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:latestThe 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-qdrantOnce connected from an MCP client, a typical first exchange looks like:
qdrant_health_check— confirms the configured Qdrant instance is reachable before doing anything else.qdrant_collection_create—{"collection_name": "docs", "vector_size": 4, "distance": "Cosine"}.qdrant_points_upsert—{"collection_name": "docs", "points": [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"title": "hello"}}]}.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-qdrantIn 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_createwithtext_model(creates adensevector of the model's size and records it) and/ortext_language(adds a BM25 index on the text field: stemmed, accent-folded, stopwords removed).Existing collection —
qdrant_collection_updatewithtext_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 atextpayload index with"scoring": true(and astemmer) on the text field withqdrant_payload_index_create.Write —
qdrant_points_upsertwith{"id": 1, "text": "..."}instead of a vector: one text is one point, nothing is split.Query —
qdrant_querywithquery_text(semantic),bm25_query(keywords), or both asprefetchstages 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.
Prompt | Arguments | Needs toolsets | What it does |
|
|
| Doctor, then recall/latency for a few |
|
|
| New collection with the settings you choose, copy, compare counts, measure, switch the alias; the old collection is kept. |
|
|
| Find the text field, declare the embedding model you name (never guessed), add a BM25 index for the language, try semantic, keyword and hybrid queries. |
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.
Variable | Default | Required | Purpose |
| — | No¹ | URL of your Qdrant instance, e.g. |
| — | No | API key for |
| — | No¹ | Path to an embedded/on-disk Qdrant instance, instead of a URL. |
|
| No | Removes every tool not marked read-only from the registry. See Read-Only Mode. |
|
| No |
|
|
| No | Comma-separated list of toolsets to register. See Available Tools. |
| — | Yes, for | Bearer token clients must send in the |
|
| No | Bind host for |
|
| No | Bind port for |
| — | No | Comma-separated |
|
| No | Largest number of points one tool call may ask for (minimum 30, so every tool's default request fits) ( |
¹ 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, plusqdrant_queryand theqdrant_health_checksmoke 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).
Tool | Toolset | Read-only | Destructive | Idempotent | Description |
|
| ✅ | ❌ | ✅ | Confirm the configured Qdrant instance is reachable and responding. |
|
| ❌ | ❌ | ❌ | Create a collection: a single unnamed vector ( |
|
| ✅ | ❌ | ✅ | List every collection name in the configured Qdrant instance. |
|
| ✅ | ❌ | ✅ | Return full config and status of one collection. |
|
| ❌ | ❌ | ✅ | Update optimizer/HNSW/collection/vector params on an existing collection. |
|
| ❌ | ✅ | ✅ | Delete a collection and all its points; a no-op if it doesn't exist. |
|
| ✅ | ❌ | ✅ | Check whether a collection exists, without raising if it doesn't. |
|
| ❌ | ✅ | ✅ | Insert or replace points (id + vector or text + payload) in a collection. |
|
| ✅ | ❌ | ✅ | Retrieve points by id; unknown ids are simply omitted, not an error. |
|
| ❌ | ✅ | ✅ | Delete points by id list or by payload filter — exactly one of the two. |
|
| ✅ | ❌ | ✅ | Page through all points in a collection, optionally filtered. |
|
| ✅ | ❌ | ✅ | Count points in a collection, optionally matching a filter. |
|
| ✅ | ❌ | ✅ | Search a collection with Qdrant's unified Query API: vector similarity, hybrid fusion, multi-stage reranking, MMR diversity, payload-based score formulas, ordering by a payload field, or random sampling. |
|
| ✅ | ❌ | ✅ | Run multiple independent queries against one collection in a single round trip — each item takes every query mode and tuning parameter of |
|
| ✅ | ❌ | ✅ | Vector query grouped by a payload field, up to |
|
| ✅ | ❌ | ✅ | 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. |
|
| ✅ | ❌ | ✅ | Run multiple independent recommend queries against one collection in a single round trip. |
|
| ✅ | ❌ | ✅ | Recommend query grouped by a payload field, up to |
|
| ✅ | ❌ | ✅ | 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. |
|
| ✅ | ❌ | ✅ | Run multiple independent discover queries against one collection in a single round trip. |
|
| ✅ | ❌ | ✅ | Pairwise distance matrix between a random sample of points: for each of |
|
| ✅ | ❌ | ✅ | Same distance matrix as |
|
| ❌ | ❌ | ✅ | Merge fields into the payload of selected points — exactly one of |
|
| ❌ | ✅ | ✅ | Replace the entire payload of selected points with |
|
| ❌ | ✅ | ✅ | Delete specific payload keys from selected points — exactly one of |
|
| ❌ | ✅ | ✅ | Wipe the entire payload of selected points, keeping their vectors — exactly one of |
|
| ✅ | ❌ | ✅ | Count distinct values of a payload field across the collection (or a filtered subset) — e.g. how many points per |
|
| ❌ | ✅ | ✅ | Create a payload index on |
|
| ❌ | ✅ | ✅ | Delete the payload index on |
|
| ❌ | ❌ | ✅ | Add a new named vector (dense or sparse) to a collection that already has points, without touching them. |
|
| ❌ | ✅ | ✅ | Remove a named vector (dense or sparse) from a collection — points keep their other vectors and payload. |
|
| ❌ | ✅ | ❌ | Run multiple point operations (upsert, delete, set/overwrite/delete/clear payload, update/delete vectors) against one collection, in the order given, in a single request. |
|
| ❌ | ✅ | ✅ | Replace the vector(s) of existing points by id — leaves their payload untouched. |
|
| ❌ | ✅ | ✅ | Remove specific named vectors from selected points, keeping their payload and other vectors — exactly one of |
|
| ✅ | ❌ | ✅ | List every alias on the server with the collection it points to. |
|
| ✅ | ❌ | ✅ | List the aliases that point to one collection (an empty list if it has none). |
|
| ❌ | ✅ | ❌ | Create, rename, re-point or delete aliases — the basis of a zero-downtime reindex: build the new collection, then switch the alias that clients use. |
|
| ✅ | ❌ | ✅ | Shard layout of a collection: how many shards it has and, for each local shard, its point count and replica state. |
|
| ✅ | ❌ | ✅ | Progress of the background optimizer for a collection — answers "has it finished indexing?" and "why isn't the collection green?". |
|
| ❌ | ✅ | ✅ | Copy points (all vectors — dense, sparse and multivector — and payload) from one collection to another of the same Qdrant instance, entirely server-side: the vectors never pass through the model. |
|
| ✅ | ❌ | ✅ | Profile the payload keys that actually occur in a collection, so filters can be written against real keys instead of guessed ones. |
|
| ✅ | ❌ | ✅ | Diagnose one collection (or alias): read-only checks that each come with the exact tool call that acts on them, so you don't have to know Qdrant's internals. |
|
| ✅ | ❌ | ✅ | Measure how much a collection's approximate (HNSW, quantized) search loses against an exact one, and what each configuration costs in latency — so a tuning change is judged by numbers. |
|
| ❌ | ❌ | ❌ | Create a snapshot of one collection's current state. |
|
| ✅ | ❌ | ✅ | List the snapshots stored for one collection. |
|
| ❌ | ✅ | ✅ | Delete a collection snapshot, freeing its disk space on the server — does not touch the live collection. |
|
| ❌ | ✅ | ✅ | Restore the points (vectors and payload) captured in a snapshot into |
|
| ✅ | ❌ | ✅ | 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. |
|
| ❌ | ❌ | ❌ | Create a snapshot of the whole storage: a snapshot of every collection plus the alias mapping (verified: no server configuration is included), not just one collection. |
|
| ✅ | ❌ | ✅ | List the full-storage snapshots stored on the server. |
|
| ❌ | ✅ | ✅ | Delete a full-storage snapshot, freeing its disk space. |
|
| ✅ | ❌ | ✅ | Confirm a full-storage snapshot exists and return where to fetch it from — same caveat as |
|
| ✅ | ❌ | ✅ | Server-wide telemetry: build info, the number of collections and request counters by default; pass |
|
| ✅ | ❌ | ✅ | 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 |
|
| ✅ | ❌ | ✅ | Current server-wide resource quotas (memory/disk limits) and actual usage. |
|
| ❌ | ✅ | ✅ | Replace the server-wide resource quotas. |
|
| ✅ | ❌ | ✅ | List the issues Qdrant has detected about its own configuration (e.g. a heavily-filtered field with no payload index). |
|
| ❌ | ✅ | ✅ | Clear all accumulated issues. |
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
AsyncQdrantClientis 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 (theqdrant-clientSDK itself only exposes a timeout, not retries), and translated into an MCPToolErrorcarrying Qdrant's own error message instead of a generic failure — so "collection not found" reads as exactly that.stdio-safe logging. All logging goes tostderr, configured before the MCP server object is even constructed — writing tostdoutunder thestdiotransport would corrupt the JSON-RPC message framing.
Security
Mandatory authentication for
streamable-http. The server refuses to start withoutQDRANT_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_recovermakes the Qdrant server itself fetchlocation, so it only acceptsfile://paths,QDRANT_URL's own origin and the origins listed inQDRANT_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_ONLYremoves every mutating tool from the registry — see Read-Only Mode.
Development
git clone https://github.com/avaazquezz/Qdrant-MCP.git
cd Qdrant-MCP
uv sync --dev --extra embeddings
uv run pre-commit installuv run ruff check . # lint
uv run ruff format --check . # formatting
uv run mypy . # type checking (strict)
uv run pytest # unit tests
uv 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 # regenerate
uv 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
Available Tools
13 toolsqdrant_collection_createCreate Qdrant collectionA
Create a collection: a single unnamed vector (vector_size +
distance), 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), or a text collection (text_model) — exactly
one of the three. sparse_vectors defines sparse (keyword-style)
vectors at creation time.
Text: `text_model` (a fastembed model, e.g.
`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`, 384 dims,
multilingual, downloaded on first use) creates a `dense` Cosine vector
of the model's size and records the model in the collection's metadata,
so `text` in `qdrant_points_upsert` and `query_text` in `qdrant_query`
embed with it. `text_language` (e.g. "spanish") adds a BM25 index on
`text_field` (default `text`) for `bm25_query`: stemmed, accent-folded,
stopwords removed where Qdrant has a list for the language (all but
armenian and tamil); given alone, it makes a keyword-only collection
with no vectors. The embedded local mode (QDRANT_LOCAL_PATH) can't rank
such an index — BM25 there needs the default tokenization.
`quantization_config` (scalar/product/binary) and
`strict_mode_config` apply to the whole collection.
`hnsw_config` and `optimizers_config` set the index and optimizer
parameters from the start (they can also be changed later with
`qdrant_collection_update`); `on_disk_payload=true` keeps payloads
on disk instead of in RAM, which can only be chosen here.
Fails with a clear error if a collection with this name already exists.
Example (simple): {"collection_name": "docs", "vector_size": 4, "distance": "Cosine"}
Example (hybrid): {"collection_name": "docs", "vectors": {
"dense": {"size": 4, "distance": "Cosine"}
}, "sparse_vectors": {"sparse": {}}}
Example (multitenant index, payload on disk): {"collection_name": "docs",
"vector_size": 4, "hnsw_config": {"m": 0, "payload_m": 16},
"on_disk_payload": true}
Example (text, semantic + BM25): {"collection_name": "notes", "text_model":
"sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
"text_language": "spanish"}
Inputs: collection_name (required), vectors, distance, metadata, +10 more. Returns: Current statistics and configuration of the collection
qdrant_collection_deleteDelete Qdrant collectionADestructiveIdempotent
Delete a collection and all its points; a no-op if it doesn't exist.
Example: {"collection_name": "docs"}
Inputs: collection_name (required). Returns: True if the collection existed and was removed; False is a no-op, not an error…
qdrant_collection_existsCheck Qdrant collection existenceARead-onlyIdempotent
Check whether a collection exists, without raising if it doesn't.
Example: {"collection_name": "docs"}
Inputs: collection_name (required). Returns: exists
qdrant_collection_infoGet Qdrant collection infoARead-onlyIdempotent
Return full config and status of one collection.
Fails with a clear error if the collection doesn't exist.
Example: {"collection_name": "docs"}
Inputs: collection_name (required). Returns: Current statistics and configuration of the collection
qdrant_collection_listList Qdrant collectionsARead-onlyIdempotent
List every collection name in the configured Qdrant instance.
Example: {}
Inputs: no named parameters. Returns: collections
qdrant_collection_updateUpdate Qdrant collectionAIdempotent
Update optimizer/HNSW/collection/vector params on an existing collection.
`text_models` declares which fastembed model made each existing dense
vector (`{"<vector name>": "<model>"}`, `""` for the unnamed vector), so
`query_text` and `text` upserts work on a collection built elsewhere —
it must be the model the stored vectors were made with, and its size
must match the vector's. `null` removes a declaration (e.g. after
deleting that vector). A collection with points won't switch a vector
to a different model: remove the declaration first if it was wrong.
`text_field` names the payload field holding the text (default `text`).
Both are kept in the collection's metadata.
Only the fields you pass are changed; omitted ones keep their current
value. `quantization_config="disabled"` turns quantization off.
`vectors_config`/`sparse_vectors_config` only **adjust** named
vectors that already exist (HNSW/quantization/index tuning) — they
cannot add a new one; use `qdrant_collection_vector_create` for
that, or this fails with Qdrant's own "Not existing vector name"
error. Fails with a clear error if the collection doesn't exist.
Example: {"collection_name": "docs", "optimizers_config": {"indexing_threshold": 10000}}
Inputs: collection_name (required), text_field, hnsw_config, text_models, +6 more. Returns: Current statistics and configuration of the collection
qdrant_health_checkQdrant health checkARead-onlyIdempotent
Confirm the configured Qdrant instance is reachable and responding.
Never raises to the caller: a health check that raises on the exact
condition it exists to detect defeats its own purpose. Connection
failures are logged and reported in the result's ok/error fields
instead, so a client renders them without a tool-call error round-trip.
Inputs: no named parameters. Returns: Outcome of a live round-trip to the configured Qdrant instance.
qdrant_points_countCount Qdrant pointsBRead-onlyIdempotent
Count points in a collection, optionally matching a filter.
Example: {"collection_name": "docs"}
Inputs: collection_name (required), exact, count_filter. Returns: count
qdrant_points_deleteDelete Qdrant pointsADestructiveIdempotent
Delete points by id list or by payload filter — exactly one of the two.
Deleting an id that doesn't exist is not an error (Qdrant treats it as
a no-op); this only fails if the collection itself is missing, or if
you provide zero or both selectors.
Example (by id): {"collection_name": "docs", "ids": [1, 2]}
Example (by filter): {"collection_name": "docs", "points_filter": {
"must": [{"key": "city", "match": {"value": "ny"}}]
}}
Inputs: collection_name (required), ids, points_filter. Returns: status, operation_id
qdrant_points_getGet Qdrant points by idARead-onlyIdempotent
Retrieve points by id; unknown ids are simply omitted, not an error.
Fails only if the collection itself doesn't exist. `with_payload` takes
`true`/`false` or a list of keys to return only those (e.g. `["title"]`).
Example: {"collection_name": "docs", "ids": [1, 2], "with_payload": ["title", "url"]}
Inputs: ids (required), collection_name (required), with_payload, with_vectors. Returns: points
qdrant_points_scrollScroll Qdrant pointsARead-onlyIdempotent
Page through all points in a collection, optionally filtered.
Pass the returned `next_page_offset` as `offset` to fetch the next
page; `null` means there are no more pages. `limit` is capped per call
by the server's QDRANT_MCP_MAX_LIMIT (1000 by default). `with_payload`
takes `true`/`false` or a list of keys to return only those.
`order_by` sorts by a payload field instead of by id: a key, or
`{"key": ..., "direction": "asc"|"desc", "start_from": value}`; the key
needs a payload range index (integer, float or datetime). Paging works
differently then: `offset` is rejected, and `next_page_offset` is always
`null` even when more points remain — to continue, repeat the call with
`start_from` set to the last value you received (points tied on that
value are returned again, so de-duplicate by id).
Example: {"collection_name": "docs", "limit": 50}
Example (newest first): {"collection_name": "docs", "limit": 20,
"order_by": {"key": "created_at", "direction": "desc"}}
Inputs: collection_name (required), limit, offset, order_by, +3 more. Returns: points, next_page_offset
qdrant_points_upsertUpsert Qdrant pointsADestructiveIdempotent
Insert or replace points (id + vector or text + payload) in a collection.
`vector` matches the collection's vector config: a plain list for a
single unnamed vector; a list of lists for an unnamed multivector;
or a dict keyed by vector name for named vectors, where each value
is a dense list, a multivector, or a sparse vector
(`{"indices": [...], "values": [...]}`). Give `text` instead of `vector`
to have it embedded with every model the collection declares (see
`qdrant_collection_create`'s `text_model`) and stored in its text field
— one text is one point, nothing is split. A text longer than the model
reads (128 tokens, ~500 characters, for the multilingual MiniLM) is
refused rather than silently cut: split it into several points. Needs
the `embeddings` extra.
`update_mode` makes the write conditional: `insert_only` never
overwrites an existing id, `update_only` never creates a new one
(default `upsert` does both). `update_filter` only overwrites existing
points whose current payload matches the filter; ids that don't exist
yet are inserted regardless (verified). `wait=false`
returns before the write is applied.
Fails with a clear error if the collection doesn't exist.
Example: {"collection_name": "docs", "points": [
{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"city": "ny"}}
]}
Example (text): {"collection_name": "notes", "points": [
{"id": 1, "text": "Grants for young people's housing", "payload": {"year": 2026}}
]}
Example (named dense + sparse): {"collection_name": "docs", "points": [
{"id": 1, "vector": {"dense": [0.1, 0.2, 0.3, 0.4],
"sparse": {"indices": [1, 7], "values": [0.5, 0.2]}}}
]}
Inputs: points (required), collection_name (required), wait, update_mode, +1 more. Returns: status, operation_id
qdrant_queryQuery QdrantARead-onlyIdempotent
Search a collection with Qdrant's unified Query API: vector similarity, hybrid fusion, multi-stage reranking, MMR diversity, payload-based score formulas, ordering by a payload field, or random sampling.
Exactly one query mode is required:
- `query_vector` — nearest points to a dense vector, a multivector (list
of vectors), a sparse vector (`{"indices": [...], "values": [...]}`),
or a point id whose stored vector is reused (that point itself is left
out of the results). It must match the vector
selected with `using`. Add `mmr` (`diversity` 0..1,
`candidates_limit`) to re-order the nearest candidates for diversity:
set `candidates_limit` well above `limit` (it defaults to `limit`,
which leaves MMR nothing to choose from). `offset` pages through the
MMR ranking on Qdrant 1.20 (verified; older servers applied it inside
the `limit` re-ranked results, so raise `limit` there instead).
- `query_text` — semantic search with plain text: embedded with the model
the collection declares for the vector in `using` (`using` can be
omitted when it declares exactly one). Needs the `embeddings` extra;
`mmr` works as with `query_vector`.
- `bm25_query` — keyword search ranked by BM25 (Qdrant 1.20): `using` is
a payload field whose `text` index has `scoring` set (defaults to the
collection's declared text field). The index's own tokenizer, stemmer
and stopwords apply. Needs no embeddings.
- `fusion` + 2+ `prefetch` stages — combine retrieval strategies:
`"rrf"` (Reciprocal Rank Fusion), `"dbsf"` (Distribution-Based Score
Fusion), or `{"method": "rrf", "weights": [2, 1], "k": 60}` for RRF
with one weight per stage (a count that doesn't match the stages is
rejected by Qdrant).
- `formula` — rescore the results of `prefetch` stages (required: a
formula without prefetch is rejected). `{"expression": ..., "defaults":
{...}}`. An expression is a number; a variable (`"$score"` is the
prefetch score, any other string is a payload key); a payload
condition (e.g. `{"key": "city", "match": {"value": "sf"}}`, worth 1
if it matches, else 0); or exactly one operator object: `{"sum":
[...]}`, `{"mult": [...]}`, `{"neg": e}`, `{"abs": e}`, `{"div":
{"left": e, "right": e}}`, `{"sqrt": e}`, `{"pow": {"base": e,
"exponent": e}}`, `{"exp": e}`, `{"ln": e}`, `{"log10": e}`,
`{"geo_distance": {"origin": {"lat": .., "lon": ..}, "to":
"payload.key"}}`, `{"datetime": "2026-01-01T00:00:00Z"}`,
`{"datetime_key": "payload.key"}`, and the decays `{"exp_decay" |
"gauss_decay" | "lin_decay": {"x": e, "target": e, "scale": number,
"midpoint": number}}`. A payload key a point lacks needs a value in
`defaults`, or Qdrant rejects the query.
- `order_by` — sort by a payload field instead of by similarity: a key
or `{"key": ..., "direction": "asc"|"desc", "start_from": value}`.
The key needs a payload range index (integer, float or datetime).
- `sample: "random"` — random points.
A `prefetch` stage is itself a `query_vector`, `query_text` or
`bm25_query` query, or a `fusion` of its own nested `prefetch` stages,
so pipelines nest: fuse semantic + BM25 in one stage, then rerank. `using` selects a named
vector; `lookup_from` resolves `query_vector` from a point id in
another collection.
Results: `with_payload` takes `true`/`false` or a list of keys to return
only those (e.g. `["title", "url"]`, nested ones as `"meta.author"`) —
most of what you read back is payload.
Tuning: `search_params` (`hnsw_ef`, `exact` for brute force,
`quantization`: `ignore`/`rescore`/`oversampling`, `indexed_only`,
`acorn`), `score_threshold` (drop weaker hits), `limit` + `offset`
(paging; `limit` is capped per call by the server's QDRANT_MCP_MAX_LIMIT,
1000 by default — page with `offset` for more), `timeout_seconds`
(server-side), and `consistency` (a replica count, or
`"majority"`/`"quorum"`/`"all"`; only meaningful on a replicated
deployment). Fails with a clear error if the collection doesn't exist.
Example (plain): {"collection_name": "docs", "query_vector": [0.1, 0.2, 0.3, 0.4],
"limit": 5}
Example (by text): {"collection_name": "docs", "query_text": "housing grants", "limit": 5}
Example (semantic + BM25): {"collection_name": "docs", "fusion": "rrf", "prefetch": [
{"query_text": "housing grants", "limit": 20},
{"bm25_query": "housing grants", "limit": 20}
], "limit": 5}
Example (hybrid): {"collection_name": "docs", "fusion": "rrf", "prefetch": [
{"query_vector": [0.1, 0.2, 0.3, 0.4], "using": "dense", "limit": 20},
{"query_vector": {"indices": [1, 7], "values": [0.5, 0.2]}, "using": "sparse",
"limit": 20}
], "limit": 5}
Example (diverse results): {"collection_name": "docs", "query_vector": [0.1, 0.2, 0.3, 0.4],
"mmr": {"diversity": 0.5, "candidates_limit": 50}, "limit": 5}
Example (boost one city): {"collection_name": "docs", "prefetch": [
{"query_vector": [0.1, 0.2, 0.3, 0.4], "limit": 50}
], "formula": {"expression": {"sum": ["$score",
{"mult": [0.5, {"key": "city", "match": {"value": "sf"}}]}]}}, "limit": 5}
Example (cheapest first): {"collection_name": "docs", "order_by": {"key": "price",
"direction": "asc"}, "limit": 5}
Inputs: collection_name (required), mmr, limit, using, +17 more. Returns: points
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool targets a clearly distinct resource+action: collection lifecycle (create/list/info/update/delete/exists), point lifecycle (upsert/get/delete/scroll/count), a single query tool, and a health check. The nearest overlaps — points_get (by id) vs points_scroll (paging) vs points_count vs query — are separated cleanly by their argument shapes and descriptions. No two tools appear interchangeable.
Names follow a predictable qdrant_<resource>_<verb> pattern (qdrant_collection_create, qdrant_points_upsert, qdrant_points_scroll, etc.), with the resource group always spelled out. The only deviations are qdrant_query (verb-only, no resource) and qdrant_health_check, which are minor but break the otherwise uniform scheme.
13 tools is well within the ideal 3-15 range and each tool maps to a real, non-redundant operation on a vector database. Nothing feels padded; the collection/point split is economical.
Core collection and point CRUD is covered, but there are notable gaps: qdrant_collection_update explicitly directs users to 'qdrant_collection_vector_create' for adding named vectors, yet that tool is not exposed. There is also no payload-index management tool, even though query/scroll's order_by requires a range index that cannot be created with this surface.
Maintenance
Related MCP Connectors
AgentReady Tools is a searchable catalog of more than 250 APIs, MCP servers and developer tools that AI agents can use, each with agent-readiness checks (docs, auth, OpenAPI, MCP support). Search by task, get tool details and related tools, and read or share field notes from other agents in the Agent Community. Remote MCP endpoint: https://agentready-tools.com/mcp
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Astra DB tools for agents: schema, find, vector search, guarded writes, and interactive views.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to perform semantic search, manage vectors, and interact with Pinecone vector databases through standardized MCP tools. Supports querying, upserting, deleting vectors and monitoring database statistics for knowledge base operations.18 npm-
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Qdrant vector database for storing, searching, and managing vectors with automatic text embedding.1-
- FlicenseNot gradedqualityDmaintenanceEnables RAG (Retrieval-Augmented Generation) with tools for vector search, document access, and OpenAI integration, plus MySQL storage and file system operations via MCP.-
- AlicenseAqualityDmaintenanceExposes hybrid retrieval (dense embeddings + BM25 + RRF) and document operations (search, fetch, rerank) as MCP tools, using Qdrant and OpenAI embeddings for local or server mode.3MIT