qdrant-mcp

A Model Context Protocol (MCP) server for Qdrant with support for any OpenAI-compatible embeddings API — Mistral, OpenAI, Voyage, Together, DeepInfra, local Ollama-via-OpenAI-shim, etc.

Why

A small MCP server with a configurable embedding endpoint, so you can use whichever provider fits your project — Mistral, OpenAI, Voyage, Together, or anything else that exposes an OpenAI-compatible /embeddings endpoint. Three runtime dependencies, native fetch, no LangChain.

Features

• 5 tools: list_collections, add_text, add_file, search, delete_collection
• OpenAI-compatible embeddings — set endpoint, model and dimension via env vars
• Auto-creates collections with the correct dimension on first ingest
• Recursive character splitter, no LangChain dependency
• File ingest for .txt, .md, .markdown, .pdf
• Qdrant payload filters in search
• Embedding-dimension validation against the configured value (catches model/dim mismatch early)
• Access control via collection allowlist and optional read-only mode

Install

git clone <this repo>
cd qdrant-mcp
npm install
npm run build

Requires Node.js >= 18.

Configuration

All settings come from environment variables.

| Variable | Required | Default | Description | |---|---|---|---| | QDRANT_URL | no | http://localhost:6333 | Qdrant base URL | | QDRANT_API_KEY | no | — | Qdrant API key (Cloud / secured instances) | | QDRANT_DISTANCE | no | Cosine | Cosine, Euclid, Dot, or Manhattan | | QDRANT_COLLECTIONS | no | — | Comma-separated allowlist. If set, only these collections are visible to list_collections and usable by all other tools. | | QDRANT_READ_ONLY | no | false | true/1/yes disables add_text, add_file and delete_collection. search and list_collections remain available. | | EMBEDDING_ENDPOINT | yes | — | Base URL ending in /v1 (the server appends /embeddings) | | EMBEDDING_API_KEY | yes | — | Sent as Authorization: Bearer … | | EMBEDDING_MODEL | yes | — | Model name to send to the API | | EMBEDDING_DIMENSION | yes | — | Vector dimension; must match what the model returns | | EMBEDDING_BATCH_SIZE | no | 100 | Batch size for embedding calls | | CHUNK_SIZE | no | 1000 | Default chunk size in characters | | CHUNK_OVERLAP | no | 200 | Default overlap between chunks |

Provider examples

Mistral

EMBEDDING_ENDPOINT=https://api.mistral.ai/v1
EMBEDDING_MODEL=mistral-embed
EMBEDDING_DIMENSION=1024

OpenAI

EMBEDDING_ENDPOINT=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSION=1536

Voyage

EMBEDDING_ENDPOINT=https://api.voyageai.com/v1
EMBEDDING_MODEL=voyage-3
EMBEDDING_DIMENSION=1024

See .env.example for the full template.

Usage with Claude Desktop / Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "qdrant": {
      "command": "node",
      "args": ["/absolute/path/to/qdrant-mcp/build/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "EMBEDDING_ENDPOINT": "https://api.mistral.ai/v1",
        "EMBEDDING_API_KEY": "your-key",
        "EMBEDDING_MODEL": "mistral-embed",
        "EMBEDDING_DIMENSION": "1024"
      }
    }
  }
}

Tools

list_collections

No arguments. Returns the names of all collections.

add_text

Embed and store raw text. Creates the collection on first call.

{
  "text": "Long document text here…",
  "collection": "my-docs",
  "source": "manual-2024-q4",
  "metadata": { "team": "platform" },
  "chunkSize": 1000,
  "chunkOverlap": 200
}

add_file

Same as add_text but reads from disk. Supports .txt, .md, .markdown, .pdf.

{
  "filePath": "/abs/path/to/handbook.pdf",
  "collection": "my-docs",
  "metadata": { "category": "policy" }
}

search

Semantic search with optional Qdrant filter. The filter field is passed straight through, so the full Qdrant filter syntax is available.

{
  "query": "what is the parental leave policy?",
  "collection": "my-docs",
  "limit": 5,
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "policy" } }
    ]
  }
}

delete_collection

{ "collection": "my-docs" }

Development

npm run dev      # tsc --watch
npm run build    # one-shot build
npm start        # node build/index.js (expects env)

License

MIT