Qdrant-MCP

# Qdrant MCP

<!-- mcp-name: io.github.avaazquezz/mcp-qdrant -->

[![PyPI version](https://img.shields.io/pypi/v/mcp-qdrant.svg)](https://pypi.org/project/mcp-qdrant/)
[![CI](https://github.com/avaazquezz/Qdrant-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/avaazquezz/Qdrant-MCP/actions/workflows/ci.yml)
[![Python versions](https://img.shields.io/pypi/pyversions/mcp-qdrant.svg)](https://pypi.org/project/mcp-qdrant/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**A Model Context Protocol (MCP) server that exposes the full [Qdrant](https://qdrant.tech)
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](#overview)
- [Key Features](#key-features)
- [Requirements](#requirements)
- [Installation](#installation)
  - [PyPI](#pypi)
  - [Docker](#docker)
  - [Claude Desktop bundle (`.mcpb`)](#claude-desktop-bundle-mcpb)
- [Quick Start](#quick-start)
- [Connecting to Claude](#connecting-to-claude)
  - [Claude Desktop / Claude Code (local, stdio)](#claude-desktop--claude-code-local-stdio)
  - [Remote (streamable-http)](#remote-streamable-http)
- [Configuration Reference](#configuration-reference)
- [Available Tools](#available-tools)
- [Read-Only Mode](#read-only-mode)
- [Architecture](#architecture)
- [Security](#security)
- [Development](#development)
- [Versioning & Changelog](#versioning--changelog)
- [License](#license)

## Overview

Qdrant MCP is a thin [MCP](https://modelcontextprotocol.io) 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](https://github.com/qdrant/mcp-server-qdrant), 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](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 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.
- **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** — 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.
- **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 ~44 KB of schema instead of ~150 KB, 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.** 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

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

# Or install into your environment
pip install mcp-qdrant
```

### Docker

```bash
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](https://github.com/avaazquezz/Qdrant-MCP/releases)
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:

```bash
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](#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):

```json
{
  "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](#claude-desktop-bundle-mcpb) — 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).

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

## 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](#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](#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