Better Qdrant MCP

更好的qdrant mcp

MCP服务器用 fastmcp、OpenAI嵌入，以及 qdrant-client，在Qdrant之上提供长期记忆和语义搜索。

用户指南

特性

• MCP服务器 建于 fastmcp
• 混合搜索 在Qdrant中（密集的OpenAI嵌入+稀疏的BM25）
• 中文支持 经街坝
• 知识库工具 （从内存工具重命名以避免冲突）：

- store-knowledge - store-knowledge-bulk - search-knowledge - get-knowledge-by-id - inspect-knowledge-base - delete-knowledge

• 多个传输：stdio、SSE、可流式传输HTTP

需求

• Python 3.12+
• Qdrant可通过HTTP访问

快速入门（已发布的软件包）

该项目发布为 better-qdrant-mcp 包，因此您可以直接使用 uvx 无需克隆此仓库。

1.环境变量（所有运输都需要）

典型使用的最小环境值：

• QDRANT_URL –默认为 http://localhost:6333
• QDRANT_API_KEY –可选
• COLLECTION_NAME –可选默认集合
• OPENAI_API_KEY （或 OPENAPI_API_KEY)–必填
• OPENAI_BASE_URL –可选
• OPENAI_EMBEDDING_MODEL –默认为 text-embedding-3-small

高级/运输相关环境：

• MCP_TRANSPORT – stdio | sse | streamable-http （默认值： stdio)
• MCP_HOST –用于基于HTTP的传输的主机（默认值： 0.0.0.0)
• MCP_PORT –用于基于HTTP的传输的端口（默认值： 8000)
• MCP_PATH –HTTP传输路径（默认值： /mcp)

2.可用的MCP工具

服务器运行后，MCP客户端将看到以下工具：

• store-knowledge(content: str, title?: str, tags?: list[str], metadata?: dict, collection_name?: str) -> str
• store-knowledge-bulk(items: list[KnowledgeItem], collection_name?: str) -> str
• search-knowledge(query: str, limit?: int=5, collection_name?: str) -> str
• get-knowledge-by-id(ids: list[str] | str, collection_name?: str) -> str
• inspect-knowledge-base(collection_name?: str) -> str
• delete-knowledge(ids: list[str] | str, collection_name?: str) -> str

store-knowledge 使用OpenAI自动嵌入文本并将其存储在Qdrant（知识库）中，返回存储的点ID title 和 tags 字段有助于改善搜索上下文和分类。

store-knowledge-bulk 使用批嵌入一次有效地存储多个知识项。清单中的每一项都应包括 content （必填），可选 title, tags，以及 metadata 领域。这比打电话更有效率 store-knowledge 多次。

search-knowledge 在Qdrant中使用混合搜索（密集+稀疏）。如果集合配置了命名向量 dense 和 sparse，通过融合密集的OpenAI嵌入和稀疏的BM25分数对查询进行排名；否则，它将退回到仅密集搜索。

get-knowledge-by-id 通过一个或多个知识项的点ID检索其完整的有效载荷信息。使用此功能检查存储项目的全部详细信息（包括 content, title, tags, metadata，以及 stored_at 时间戳）。您可以传递单个ID或ID列表（通常使用 id 字段返回 search-knowledge).

inspect-knowledge-base 显示了收集配置和示例数据点，可用于调试和验证。

delete-knowledge 按点ID从Qdrant中删除一个或多个存储的知识项。您可以传递单个ID或ID列表（通常使用 id 字段返回 search-knowledge).

3.启动服务器

您可以通过CLI标志（建议快速启动）或通过env指定传输(MCP_TRANSPORT).

标准IO（stdio）-默认

uvx better-qdrant-mcp

在此模式下，您可以将MCP客户端配置为使用 标准 传输并仅调用二进制文件；不需要HTTP URL。

服务器发送事件（SSE）

# Default host 0.0.0.0 and port 8000
uvx better-qdrant-mcp --transport sse

# Custom host and port
uvx better-qdrant-mcp --transport sse --host 0.0.0.0 --port 3000

MCP客户端的连接详细信息：

• 运输: sse
• 统一资源定位符: `http://:

/sse （例如： http://localhost:8000/sse`)

流式HTTP（推荐用于web应用程序）

# Default host 0.0.0.0, port 8000 and path /mcp
uvx better-qdrant-mcp --transport streamable-http

# Custom host, port, and path
uvx better-qdrant-mcp --transport streamable-http --host 0.0.0.0 --port 3000 --path /api/mcp

MCP客户端的连接详细信息：

• 运输: streamable-http
• 统一资源定位符: `http://:

（例如： http://localhost:8000/mcp`)

开发指南

本地安装（用于开发）

如果你想在本地处理此仓库，而不是使用已发布的包：

# using uv (recommended)
uv sync

# or with pip (editable install)
pip install -e .

本地建设

对于本地开发，您可以使用提供的 Makefile:

make build

此命令将首先清理 dist 目录，然后运行 uv build 生产新鲜的手工艺品。

Docker部署

Docker Compose将Qdrant+此MCP服务器作为单一服务提供。运输(stdio, sse, streamable-http)通过以下方式选择 MCP_TRANSPORT.

Docker镜像会自动构建并发布到GitHub容器注册表，如下所示：

• ghcr.io/jtsang4/better-qdrant-mcp:latest
• 分支、标签和提交SHA的附加标签

提供的 docker-compose.yml 直接使用此已发布的图像，因此您 不需要在本地构建映像.

# Start Qdrant + MCP using the published image
docker compose up -d

# Pull the latest published image and restart services
docker compose pull mcp && docker compose up -d

# Stop services
docker compose down

许可证

麻省理工学院