qdrant-mcp

Servidor MCP para la ingesta de documentos y búsqueda semántica en Qdrant.

Descripción general

qdrant-mcp proporciona herramientas para:

• ingerir documentos locales en una colección de Qdrant

• generar embeddings con OpenAI

• ejecutar búsquedas vectoriales con filtros de metadatos opcionales

Related MCP server: mcp-server-qdrant

Características

• ingest_documents

  • convierte archivos como docx, pptx y pdf a Markdown mediante MarkItDown

  • divide el contenido en fragmentos usando chunk_size y overlap_ratio

  • incrusta fragmentos con OpenAI Embeddings (text-embedding-3-small por defecto)

  • realiza upsert del texto del fragmento y los metadatos en Qdrant

• search_documents

  • incrusta el texto de consulta con la misma API de embeddings

  • recupera las k mejores coincidencias de Qdrant

  • admite filtrado por category y path

Requisitos

• Python 3.11+

• uv

• Qdrant (por ejemplo, http://localhost:6333)

• OPENAI_API_KEY

Configuración

uv sync

Ejecutar dentro de la CLI de Codex

[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"
}

Pruebas

Establezca OPENAI_API_KEY, QDRANT_URL y QDRANT_API_KEY en .env, luego ejecute:

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

Herramientas MCP

ingest_documents

Parámetros:

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

Retorna:

• collection

• embedding_model

• ingested_files

• ingested_points

• failed_files

search_documents

Parámetros:

• query: str

• top_k: int = 5

• category: str | None = None

• path: str | None = None

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

Retorna:

• collection

• embedding_model

• query

• count

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

delete_documents_by_path

Parámetros:

• path: str

• category: str | None = None

Retorna:

• collection

• path

• category

• status

• operation_id

list_category

Parámetros:

• limit: int = 100

Retorna:

• collection

• count

• categories

list_path

Parámetros:

• category: str

• limit: int = 1000

Retorna:

• collection

• category

• count

• paths

Notas

• Si la colección de destino no existe, se crea automáticamente en la primera ingesta.

• Si los índices de carga útil para category y path no existen, se crean durante la ingesta.

• Por defecto, la ingesta antepone un Chunk-Header generado (máximo 64 caracteres), derivado de los primeros 4096 bytes, a cada fragmento.

• El modelo de Chunk-Header se lee de CHUNK_HEADER_MODEL cuando chunk_header_mode está en enabled (por defecto: gpt-5.4-mini).

• El nombre de la colección se configura solo a través de QDRANT_COLLECTION (no mediante parámetros de la herramienta MCP).

• Con text-embedding-3-small, el tamaño del vector es 1536.

Licencia

Ver LICENSE.