qdrant-mcp

MCP server for document ingestion and semantic search on Qdrant.

Overview

qdrant-mcp provides tools to:

• ingest local documents into a Qdrant collection

• generate embeddings with OpenAI

• run vector search with optional metadata filters

Features

• ingest_documents

  • converts files such as docx, pptx, and pdf to Markdown via MarkItDown

  • splits content into chunks using chunk_size and overlap_ratio

  • embeds chunks with OpenAI Embeddings (text-embedding-3-small by default)

  • upserts chunk text and metadata into Qdrant

• search_documents

  • embeds query text with the same embeddings API

  • retrieves top k matches from Qdrant

  • supports filtering by category and path

Requirements

• Python 3.11+

• uv

• Qdrant (for example, http://localhost:6333)

• OPENAI_API_KEY

Setup

uv sync

Run inside the Codex CLI

[mcp_servers.qdrant-mcp]
command = "uv"
args = ["run", "qdrant-mcp"]
cwd = "/sandbox/qdrant-mcp"

env = {
  OPENAI_API_KEY = "sk-...",
  QDRANT_URL = "http://127.0.0.1:6333",
  QDRANT_API_KEY = "QDRANT_API_KEY",
  QDRANT_COLLECTION = "codex_collection",
  CHUNK_HEADER_MODEL = "gpt-5.4-mini"
}

Testing

Set OPENAI_API_KEY, QDRANT_URL, and QDRANT_API_KEY in .env, then run:

uv run python -m unittest tests/integration/test_qdrant_integration.py

MCP Tools

ingest_documents

Parameters:

• paths: list[str]

• category: str

• chunk_size: int = 1200

• overlap_ratio: float = 0.15

• embedding_model: str = "text-embedding-3-small"

• chunk_header_mode: Literal["enabled", "disabled"] = "enabled"

Returns:

• collection

• embedding_model

• ingested_files

• ingested_points

• failed_files

search_documents

Parameters:

• query: str

• top_k: int = 5

• category: str | None = None

• path: str | None = None

• embedding_model: str = "text-embedding-3-small"

Returns:

• collection

• embedding_model

• query

• count

• results (score, path, category, chunk_index, text)

delete_documents_by_path

Parameters:

• path: str

• category: str | None = None

Returns:

• collection

• path

• category

• status

• operation_id

list_category

Parameters:

• limit: int = 100

Returns:

• collection

• count

• categories

list_path

Parameters:

• category: str

• limit: int = 1000

Returns:

• collection

• category

• count

• paths

Notes

• If the target collection does not exist, it is created automatically on first ingestion.

• If payload indexes for category and path do not exist, they are created during ingestion.

• By default, ingestion prepends a generated Chunk-Header (max 64 chars), derived from the first 4096 bytes, to every chunk.

• The Chunk-Header model is read from CHUNK_HEADER_MODEL when chunk_header_mode is enabled (default: gpt-5.4-mini).

• The collection name is configured only through QDRANT_COLLECTION (not via MCP tool parameters).

• With text-embedding-3-small, the vector size is 1536.

License

See LICENSE.