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.