Skip to main content
Glama
io.github.avaazquezz/mcp-qdrant

io.github.avaazquezz/mcp-qdrant

by avaazquezz

Qdrant MCP

PyPI version CI Python versions License: MIT

Qdrant MCP server

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 accept text too. 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_doctor checks a collection (status, index, memory, aliases, text setup) and answers each finding with the exact tool call that fixes it; qdrant_search_quality_eval measures recall@k of the approximate search against an exact one, and latency, for any search_params variants — 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 MCP instructions), 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 core toolset 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 Filter and configuration models are summarized, validation unchanged), so the default toolset costs ~47 KB of schema instead of ~150 KB; with_payload can 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 mistaken limit from 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 returns 404 on 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 with offset). 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-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> \
  -v mcp-qdrant-models:/models \
  ghcr.io/avaazquezz/qdrant-mcp:latest

The 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-qdrant

Once connected from an MCP client, a typical first exchange looks like:

  1. qdrant_health_check — confirms the configured Qdrant instance is reachable before doing anything else.

  2. qdrant_collection_create — {"collection_name": "docs", "vector_size": 4, "distance": "Cosine"}.

  3. qdrant_points_upsert — {"collection_name": "docs", "points": [{"id": 1, "vector": [0.1, 0.2, 0.3, 0.4], "payload": {"title": "hello"}}]}.

  4. 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-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>. (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 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_create with text_model (creates a dense vector of the model's size and records it) and/or text_language (adds a BM25 index on the text field: stemmed, accent-folded, stopwords removed).

  • Existing collection — qdrant_collection_update with text_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 a text payload index with "scoring": true (and a stemmer) on the text field with qdrant_payload_index_create.

  • Write — qdrant_points_upsert with {"id": 1, "text": "..."} instead of a vector: one text is one point, nothing is split.

  • Query — qdrant_query with query_text (semantic), bm25_query (keywords), or both as prefetch stages 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

tune_search

collection

core, admin

Doctor, then recall/latency for a few search_params variants, then the smallest change with its numbers — and waits for your approval.

zero_downtime_reindex

collection, alias

core, admin

New collection with the settings you choose, copy, compare counts, measure, switch the alias; the old collection is kept.

text_search_setup

collection, language

core, payload

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

QDRANT_URL

—

No¹

URL of your Qdrant instance, e.g. http://localhost:6333 or a Qdrant Cloud URL.

QDRANT_API_KEY

—

No

API key for QDRANT_URL, if your instance requires one.

QDRANT_LOCAL_PATH

—

No¹

Path to an embedded/on-disk Qdrant instance, instead of a URL.

QDRANT_MCP_READ_ONLY

false

No

Removes every tool not marked read-only from the registry. See Read-Only Mode.

QDRANT_MCP_TRANSPORT

stdio

No

stdio (local, for Claude Desktop/Code) or streamable-http (network).

QDRANT_MCP_TOOLSETS

core

No

Comma-separated list of toolsets to register. See Available Tools.

QDRANT_MCP_SHARED_SECRET

—

Yes, for streamable-http

Bearer token clients must send in the Authorization header.

QDRANT_MCP_HTTP_HOST

127.0.0.1

No

Bind host for streamable-http. Use 0.0.0.0 in a container.

QDRANT_MCP_HTTP_PORT

8000

No

Bind port for streamable-http.

QDRANT_MCP_SNAPSHOT_ALLOWED_ORIGINS

—

No

Comma-separated http(s) origins (e.g. https://backups.example.com) qdrant_snapshot_recover may restore from, besides file:// paths and QDRANT_URL's own origin. See Security.

QDRANT_MCP_MAX_LIMIT

1000

No

Largest number of points one tool call may ask for (minimum 30, so every tool's default request fits) (limit, groups' limit × group_size, a batch's total, the number of ids, ...). A bigger request is refused with a message saying to page, not silently cut.

¹ 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, plus qdrant_query and the qdrant_health_check smoke 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

qdrant_health_check

core

✅

❌

✅

Confirm the configured Qdrant instance is reachable and responding.

qdrant_collection_create

core

❌

❌

❌

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.

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 or text + 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

✅

❌

✅

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.

qdrant_query_batch

search

✅

❌

✅

Run multiple independent queries against one collection in a single round trip — each item takes every query mode and tuning parameter of qdrant_query (vector, query_text, bm25_query, fusion over prefetch, MMR, formula, order_by, sample, search_params, score_threshold, offset); timeout_seconds and consistency apply to the whole batch.

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) against one collection, in the order given, in a single request.

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_alias_list

admin

✅

❌

✅

List every alias on the server with the collection it points to.

qdrant_collection_aliases

admin

✅

❌

✅

List the aliases that point to one collection (an empty list if it has none).

qdrant_alias_update

admin

❌

✅

❌

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.

qdrant_collection_cluster_info

admin

✅

❌

✅

Shard layout of a collection: how many shards it has and, for each local shard, its point count and replica state.

qdrant_collection_optimizations

admin

✅

❌

✅

Progress of the background optimizer for a collection — answers "has it finished indexing?" and "why isn't the collection green?".

qdrant_collection_copy

admin

❌

✅

✅

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.

qdrant_payload_schema_infer

admin

✅

❌

✅

Profile the payload keys that actually occur in a collection, so filters can be written against real keys instead of guessed ones.

qdrant_collection_doctor

admin

✅

❌

✅

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.

qdrant_search_quality_eval

admin

✅

❌

✅

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.

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

❌

✅

✅

Restore the points (vectors and payload) captured in a snapshot into collection_name — points written since the snapshot are 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: a snapshot of every collection plus the alias mapping (verified: no server configuration is included), 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, the number of collections and request counters by default; pass details_level 1 or more for per-collection stats, memory and hardware usage (verified: they are null at the default level).

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

❌

✅

✅

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

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 AsyncQdrantClient is 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 (the qdrant-client SDK itself only exposes a timeout, not retries), and translated into an MCP ToolError carrying Qdrant's own error message instead of a generic failure — so "collection not found" reads as exactly that.

  • stdio-safe logging. All logging goes to stderr, configured before the MCP server object is even constructed — writing to stdout under the stdio transport would corrupt the JSON-RPC message framing.

Security

  • Mandatory authentication for streamable-http. The server refuses to start without QDRANT_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_recover makes the Qdrant server itself fetch location, so it only accepts file:// paths, QDRANT_URL's own origin and the origins listed in QDRANT_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_ONLY removes 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 install
uv 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

MIT

Available Tools

13 tools
qdrant_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 collectionA
DestructiveIdempotent

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 existenceA
Read-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 infoA
Read-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 collectionsA
Read-onlyIdempotent

List every collection name in the configured Qdrant instance.

    Example: {}
    

Inputs: no named parameters. Returns: collections

qdrant_collection_updateUpdate Qdrant collectionA
Idempotent

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 checkA
Read-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 pointsB
Read-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 pointsA
DestructiveIdempotent

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 idA
Read-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 pointsA
Read-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 pointsA
DestructiveIdempotent

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 QdrantA
Read-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

    A3.9/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables RAG (Retrieval-Augmented Generation) with tools for vector search, document access, and OpenAI integration, plus MySQL storage and file system operations via MCP.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Exposes 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.
      3
      MIT