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

• Overview
• Key Features
• Requirements
• Installation
  • PyPI
  • Docker
  • Claude Desktop bundle (.mcpb)
• Quick Start
• Connecting to Claude
  • Claude Desktop / Claude Code (local, stdio)
  • Remote (streamable-http)
  • Bring your own Qdrant (QDRANT_MCP_BYO)
• Configuration Reference
• Available Tools
• Read-Only Mode
• Architecture
• Security
• Development
• Versioning & Changelog
• License

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 generates embeddings, never parses documents, and never decides how to chunk text — it is not a RAG system, on purpose. Whatever an LLM client wants to store or query, it brings its own vectors.

That focus is also what sets it apart from the official Qdrant MCP server, which exposes exactly two tools (store/find) and does embed documents for you. 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, not just push and pull memories through a narrow interface.

See ROADMAP.md for the full phase-by-phase design history, including every finding that shaped a decision (in Spanish).

Key Features

• Full collection & point lifecycle — create/update/delete collections, CRUD on points, scrolling, counting.
• Every Qdrant search mode — plain vector search, hybrid search (RRF/DBSF fusion with prefetch stages), grouped queries, recommend, discover, and pairwise distance matrices.
• Payload & vector editing — set/overwrite/delete/clear payload, payload indexes, facet counting, named (dense/sparse) vector management, atomic batch operations.
• Snapshots — per-collection and full-storage backup/restore.
• Observability — telemetry, Prometheus metrics endpoint, resource quotas, self-diagnosed issues.
• Opt-in tool surface — tools are grouped into toolsets you enable explicitly, so a client isn't handed 60+ overlapping tools by default.
• Read-only guard — one flag removes every mutating tool from the registry entirely.
• Bring-your-own-Qdrant mode — run a public endpoint with no database of your own; every caller supplies their own Qdrant, isolated by construction, protected by an SSRF guard.
• 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. 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, but v1.19.0+ is the only version this project tests against.

Installation

PyPI

# Run without installing (recommended for Claude Desktop/Code configs)
uvx mcp-qdrant

# Or install into your environment
pip install mcp-qdrant

Docker

docker run --rm -p 8000:8000 \
  -e QDRANT_URL=http://host.docker.internal:6333 \
  -e QDRANT_MCP_TRANSPORT=streamable-http \
  -e QDRANT_MCP_HTTP_HOST=0.0.0.0 \
  -e QDRANT_MCP_SHARED_SECRET=<a long random secret> \
  ghcr.io/avaazquezz/qdrant-mcp:latest

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

Bring your own Qdrant (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 (unlike the personal-instance mode above, which uses the same header for a shared secret).
• 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 — see Security for what the SSRF guard rejects.