qdrant-mcp

MCP-сервер для загрузки документов и семантического поиска в Qdrant.

Обзор

qdrant-mcp предоставляет инструменты для:

• загрузки локальных документов в коллекцию Qdrant

• генерации эмбеддингов с помощью OpenAI

• выполнения векторного поиска с дополнительными фильтрами метаданных

Related MCP server: mcp-server-qdrant

Функции

• ingest_documents

  • преобразует файлы, такие как docx, pptx и pdf, в Markdown с помощью MarkItDown

  • разбивает содержимое на фрагменты (чанки) с использованием chunk_size и overlap_ratio

  • создает эмбеддинги фрагментов с помощью OpenAI Embeddings (по умолчанию text-embedding-3-small)

  • выполняет upsert текста фрагмента и метаданных в Qdrant

• search_documents

  • создает эмбеддинг текста запроса с помощью того же API эмбеддингов

  • извлекает топ k совпадений из Qdrant

  • поддерживает фильтрацию по category и path

Требования

• Python 3.11+

• uv

• Qdrant (например, http://localhost:6333)

• OPENAI_API_KEY

Настройка

uv sync

Запуск внутри CLI 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"
}

Тестирование

Установите OPENAI_API_KEY, QDRANT_URL и QDRANT_API_KEY в файле .env, затем выполните:

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

Инструменты MCP

ingest_documents

Параметры:

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

Возвращает:

• collection

• embedding_model

• ingested_files

• ingested_points

• failed_files

search_documents

Параметры:

• query: str

• top_k: int = 5

• category: str | None = None

• path: str | None = None

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

Возвращает:

• collection

• embedding_model

• query

• count

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

delete_documents_by_path

Параметры:

• path: str

• category: str | None = None

Возвращает:

• collection

• path

• category

• status

• operation_id

list_category

Параметры:

• limit: int = 100

Возвращает:

• collection

• count

• categories

list_path

Параметры:

• category: str

• limit: int = 1000

Возвращает:

• collection

• category

• count

• paths

Примечания

• Если целевая коллекция не существует, она создается автоматически при первой загрузке.

• Если индексы полезной нагрузки (payload) для category и path не существуют, они создаются во время загрузки.

• По умолчанию при загрузке к каждому фрагменту добавляется сгенерированный Chunk-Header (макс. 64 символа), полученный из первых 4096 байт.

• Модель для Chunk-Header считывается из CHUNK_HEADER_MODEL, когда chunk_header_mode имеет значение enabled (по умолчанию: gpt-5.4-mini).

• Имя коллекции настраивается только через QDRANT_COLLECTION (не через параметры инструмента MCP).

• При использовании text-embedding-3-small размер вектора составляет 1536.

Лицензия

См. LICENSE.