qdrant-mcp

Qdrant 기반 문서 수집 및 의미론적 검색을 위한 MCP 서버입니다.

개요

qdrant-mcp는 다음을 위한 도구를 제공합니다:

• 로컬 문서를 Qdrant 컬렉션으로 수집

• OpenAI를 사용하여 임베딩 생성

• 선택적 메타데이터 필터를 사용하여 벡터 검색 실행

Related MCP server: mcp-server-qdrant

기능

• ingest_documents

  • MarkItDown을 통해 docx, pptx, pdf와 같은 파일을 Markdown으로 변환

  • chunk_size 및 overlap_ratio를 사용하여 콘텐츠를 청크로 분할

  • OpenAI 임베딩(기본값 text-embedding-3-small)으로 청크 임베딩

  • 청크 텍스트와 메타데이터를 Qdrant에 업서트(upsert)

• search_documents

  • 동일한 임베딩 API로 쿼리 텍스트 임베딩

  • Qdrant에서 상위 k개의 일치 항목 검색

  • category 및 path별 필터링 지원

요구 사항

• Python 3.11+

• uv

• Qdrant (예: http://localhost:6333)

• OPENAI_API_KEY

설정

uv sync

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

테스트

.env 파일에 OPENAI_API_KEY, QDRANT_URL, QDRANT_API_KEY를 설정한 후 다음을 실행하세요:

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

참고 사항

• 대상 컬렉션이 존재하지 않으면 첫 수집 시 자동으로 생성됩니다.

• category 및 path에 대한 페이로드 인덱스가 존재하지 않으면 수집 중에 생성됩니다.

• 기본적으로 수집 시 처음 4096바이트에서 파생된 생성된 Chunk-Header(최대 64자)가 모든 청크 앞에 추가됩니다.

• chunk_header_mode가 enabled(기본값: gpt-5.4-mini)일 때 Chunk-Header 모델은 CHUNK_HEADER_MODEL에서 읽어옵니다.

• 컬렉션 이름은 QDRANT_COLLECTION을 통해서만 구성됩니다(MCP 도구 매개변수를 통해서는 구성되지 않음).

• text-embedding-3-small 사용 시 벡터 크기는 1536입니다.

라이선스

LICENSE를 참조하세요.