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 Embeddings（默认为 text-embedding-3-small）对块进行嵌入

  • 将块文本和元数据插入/更新到 Qdrant

• 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 的负载索引不存在，它们会在摄入过程中创建。

• 默认情况下，摄入过程会在每个块前添加一个生成的 Chunk-Header（最大 64 字符），该头部派生自前 4096 字节。

• 当 chunk_header_mode 为 enabled（默认值：gpt-5.4-mini）时，Chunk-Header 模型从 CHUNK_HEADER_MODEL 读取。

• 集合名称仅通过 QDRANT_COLLECTION 配置（而非通过 MCP 工具参数）。

• 使用 text-embedding-3-small 时，向量大小为 1536。

许可证

参见 LICENSE。