qdrant-mcp

MCP-Server für die Dokumentenaufnahme und semantische Suche in Qdrant.

Übersicht

qdrant-mcp bietet Werkzeuge für folgende Aufgaben:

• Einlesen lokaler Dokumente in eine Qdrant-Collection

• Generieren von Embeddings mit OpenAI

• Ausführen von Vektorsuchen mit optionalen Metadatenfiltern

Related MCP server: mcp-server-qdrant

Funktionen

• ingest_documents

  • konvertiert Dateien wie docx, pptx und pdf mittels MarkItDown in Markdown

  • unterteilt Inhalte in Chunks unter Verwendung von chunk_size und overlap_ratio

  • bettet Chunks mit OpenAI Embeddings ein (standardmäßig text-embedding-3-small)

  • speichert Chunk-Text und Metadaten in Qdrant

• search_documents

  • bettet Abfragetext mit derselben Embeddings-API ein

  • ruft die besten k Treffer aus Qdrant ab

  • unterstützt das Filtern nach category und path

Anforderungen

• Python 3.11+

• uv

• Qdrant (zum Beispiel http://localhost:6333)

• OPENAI_API_KEY

Einrichtung

uv sync

Ausführung innerhalb der 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"
}

Testen

Setzen Sie OPENAI_API_KEY, QDRANT_URL und QDRANT_API_KEY in .env und führen Sie dann Folgendes aus:

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

MCP-Werkzeuge

ingest_documents

Parameter:

• 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"

Rückgabewerte:

• collection

• embedding_model

• ingested_files

• ingested_points

• failed_files

search_documents

Parameter:

• query: str

• top_k: int = 5

• category: str | None = None

• path: str | None = None

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

Rückgabewerte:

• collection

• embedding_model

• query

• count

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

delete_documents_by_path

Parameter:

• path: str

• category: str | None = None

Rückgabewerte:

• collection

• path

• category

• status

• operation_id

list_category

Parameter:

• limit: int = 100

Rückgabewerte:

• collection

• count

• categories

list_path

Parameter:

• category: str

• limit: int = 1000

Rückgabewerte:

• collection

• category

• count

• paths

Hinweise

• Wenn die Ziel-Collection nicht existiert, wird sie bei der ersten Aufnahme automatisch erstellt.

• Wenn Payload-Indizes für category und path nicht existieren, werden sie während der Aufnahme erstellt.

• Standardmäßig stellt die Aufnahme jedem Chunk einen generierten Chunk-Header (max. 64 Zeichen) voran, der aus den ersten 4096 Bytes abgeleitet wird.

• Das Chunk-Header-Modell wird aus CHUNK_HEADER_MODEL gelesen, wenn chunk_header_mode auf enabled gesetzt ist (Standard: gpt-5.4-mini).

• Der Name der Collection wird ausschließlich über QDRANT_COLLECTION konfiguriert (nicht über MCP-Werkzeugparameter).

• Bei text-embedding-3-small beträgt die Vektorgröße 1536.

Lizenz

Siehe LICENSE.