Qdrant MCP
官方使用 Qdrant 向量数据库进行语义搜索。
你可以用 Qdrant MCP 做什么?
- 存储记忆 — 让助手将信息(可选附带元数据)保存到 Qdrant 集合中,使用
qdrant-store。 - 语义搜索 — 使用自然语言
query和qdrant-find检索相关的已存储信息。 - 选择集合 — 每次调用时指定目标
collection_name,或通过COLLECTION_NAME设置默认值。 - 自定义工具描述 — 调整
TOOL_STORE_DESCRIPTION和TOOL_FIND_DESCRIPTION,将服务器改造成代码片段搜索工具。 - 只读模式 — 启用
QDRANT_READ_ONLY以禁用存储功能,仅允许检索。 - 调整结果 — 使用
QDRANT_SEARCH_LIMIT限制搜索结果数量,并通过EMBEDDING_MODEL选择嵌入模型。
文档
mcp-server-qdrant:Qdrant MCP 服务器
模型上下文协议 (MCP) 是一种开放协议,可实现 LLM 应用与外部数据源和工具之间的无缝集成。无论你是在构建 AI 驱动的 IDE、增强聊天界面,还是创建自定义 AI 工作流,MCP 都能提供一种标准化方式,将 LLM 与所需的上下文连接起来。
此仓库展示了如何为 Qdrant(一种向量搜索引擎)创建 MCP 服务器。
概述
一个官方的模型上下文协议服务器,用于在 Qdrant 向量搜索引擎中保存和检索记忆。它充当构建在 Qdrant 数据库之上的语义记忆层。
组件
工具
qdrant-store- 在 Qdrant 数据库中存储信息
- 输入:
information(string):要存储的信息metadata(JSON):要存储的可选元数据collection_name(string):用于存储信息的集合名称。如果没有默认集合名称,则此字段为必填项。 如果已设置默认集合名称,则此字段不可用。
- 返回:确认消息
qdrant-find- 从 Qdrant 数据库中检索相关信息
- 输入:
query(string):用于搜索的查询collection_name(string):用于存储信息的集合名称。如果没有默认集合名称,则此字段为必填项。 如果已设置默认集合名称,则此字段不可用。
- 返回:以独立消息形式返回存储在 Qdrant 数据库中的信息
环境变量
通过环境变量进行配置。唯一的命令行参数是 --transport,用于选择传输协议。
[!NOTE] 不能同时提供
QDRANT_URL和QDRANT_LOCAL_PATH。
| 名称 | 描述 | 默认值 |
|---|---|---|
QDRANT_URL | Qdrant 服务器的 URL | None |
QDRANT_API_KEY | Qdrant 服务器的 API 密钥 | None |
COLLECTION_NAME | 要使用的默认集合名称。 | None |
QDRANT_LOCAL_PATH | 本地 Qdrant 数据库的路径(QDRANT_URL 的替代方案) | None |
EMBEDDING_PROVIDER | 要使用的嵌入提供程序(目前仅支持 "fastembed") | fastembed |
EMBEDDING_MODEL | 要使用的嵌入模型名称 | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | store 工具的自定义描述 | 参见 settings.py 中的默认值 |
TOOL_FIND_DESCRIPTION | find 工具的自定义描述 | 参见 settings.py 中的默认值 |
QDRANT_SEARCH_LIMIT | 搜索返回结果的最大数量 | 10 |
QDRANT_READ_ONLY | 启用只读模式(禁用 qdrant-store 工具) | false |
FastMCP 环境变量
由于 mcp-server-qdrant 基于 FastMCP,因此也支持所有 FastMCP 环境变量。以下列出了其中最重要的变量:
| 环境变量 | 描述 | 默认值 |
|---|---|---|
FASTMCP_LOG_LEVEL | 设置日志级别(DEBUG、INFO、WARNING、ERROR、CRITICAL) | INFO |
FASTMCP_DEBUG | 启用调试模式 | false |
FASTMCP_HOST | 服务器绑定的主机地址(SSE 和 HTTP 传输) | 127.0.0.1 |
FASTMCP_PORT | 服务器运行的端口(SSE 和 HTTP 传输) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | 隐藏发送给客户端的工具错误消息中的异常详情 | false |
[!NOTE] 在 0.9.0 版本之前,这些设置使用
FASTMCP_SERVER_前缀,例如FASTMCP_SERVER_HOST。 旧的FASTMCP_SERVER_HOST、FASTMCP_SERVER_PORT和FASTMCP_SERVER_DEBUG名称仍然有效,但已弃用, 并将在未来版本中移除。如果同时设置了新旧名称,则以新名称为准。
安装
使用 uvx
使用 uvx 时,无需进行特定安装即可直接运行 mcp-server-qdrant。
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
传输协议
服务器支持多种传输协议,可通过 --transport 标志指定:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
支持的传输协议:
stdio(默认):标准输入/输出传输,可能仅适用于本地 MCP 客户端sse:服务器发送事件传输,非常适合远程客户端streamable-http:可流式传输的 HTTP 传输,非常适合远程客户端,且比 SSE 更新
如果未指定,默认传输协议为 stdio。
使用 SSE 传输时,服务器会在指定端口上监听并等待传入连接。默认端口为 8000,但可以通过 FASTMCP_PORT 环境变量更改。
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
使用 Docker
可使用 Dockerfile 构建并运行 MCP 服务器:
# Build the container
docker build -t mcp-server-qdrant .
# Run the container
docker run -p 8000:8000 \
-e FASTMCP_HOST="0.0.0.0" \
-e QDRANT_URL="http://your-qdrant-server:6333" \
-e QDRANT_API_KEY="your-api-key" \
-e COLLECTION_NAME="your-collection" \
mcp-server-qdrant
[!TIP] 请注意,我们将
FASTMCP_HOST="0.0.0.0"设置为让服务器监听所有网络接口。在 Docker 容器中运行服务器时,这是必需的。
通过 Smithery 安装
通过 Smithery 自动为 Claude Desktop 安装 Qdrant MCP Server:
npx @smithery/cli install mcp-server-qdrant --client claude
手动配置 Claude Desktop
要在 Claude Desktop 应用中使用此服务器,请将以下配置添加到 claude_desktop_config.json 的 "mcpServers" 部分:
{
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
"QDRANT_API_KEY": "your_api_key",
"COLLECTION_NAME": "your-collection-name",
"EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
}
}
}
本地 Qdrant 模式:
{
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
"COLLECTION_NAME": "your-collection-name",
"EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
}
}
}
如果指定名称的集合不存在,此 MCP 服务器会自动创建该集合。
默认情况下,服务器会使用 sentence-transformers/all-MiniLM-L6-v2 嵌入模型对记忆进行编码。
目前仅支持 FastEmbed 模型。
支持其他工具
此 MCP 服务器可与任何兼容 MCP 的客户端配合使用。例如,你可以将其与 Cursor 和 VS Code 配合使用,它们内置了对模型上下文协议的支持。
与 Cursor/Windsurf 配合使用
你可以通过自定义工具描述,将此 MCP 服务器配置为 Cursor 或 Windsurf 的代码搜索工具:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport
随后,你可以在 Cursor/Windsurf 的设置中配置 MCP 服务器,使用 SSE 传输协议指向正在运行的服务器。有关如何向 Cursor 添加 MCP 服务器的说明,请参阅 https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-cursor。如果你在本地运行 Cursor/Windsurf,可以使用以下 URL:
http://localhost:8000/sse
[!TIP] 我们建议使用 SSE 传输作为 Cursor/Windsurf 连接 MCP 服务器的首选方式,因为它支持远程连接。这样便于与团队共享服务器,或在云环境中使用。
此配置会将 Qdrant MCP 服务器转换为专用代码搜索工具,可用于:
- 存储代码片段、文档和实现细节
- 根据语义搜索检索相关代码示例
- 帮助开发者查找特定实现或使用模式
你可以通过存储代码片段的自然语言描述(在 information 参数中)以及实际代码(在 metadata.code 属性中)来填充数据库,然后使用描述所需内容的自然语言查询进行搜索。
[!NOTE] 上述工具描述仅为示例,可能需要根据你的具体使用场景进行自定义。请考虑调整描述,使其更符合团队的工作流程以及你想要存储和检索的代码片段类型。
**如果你已成功安装 mcp-server-qdrant,但仍无法让它与 Cursor 配合使用,请考虑创建 Cursor 规则,以便在代理生成新的代码片段时始终使用 MCP 工具。**你可以将规则限制为仅适用于特定文件类型,以避免在处理文档或其他类型的内容时使用 MCP 服务器。
与 Claude Code 配合使用
通过将 Claude Code 连接到此 MCP 服务器,你可以增强其功能,并对现有代码库进行语义搜索。
设置 mcp-server-qdrant
-
将 MCP 服务器添加到 Claude Code:
# Add mcp-server-qdrant configured for code search claude mcp add code-search \ -e QDRANT_URL="http://localhost:6333" \ -e COLLECTION_NAME="code-repository" \ -e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \ -e TOOL_STORE_DESCRIPTION="Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property." \ -e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \ -- uvx mcp-server-qdrant -
验证服务器是否已添加:
claude mcp list
在 Claude Code 中使用语义代码搜索
在 TOOL_STORE_DESCRIPTION 和 TOOL_FIND_DESCRIPTION 中指定的工具描述会指导 Claude Code 如何使用 MCP 服务器。上文提供的描述仅为示例,可能需要根据你的具体使用场景进行自定义。不过,Claude Code 应该已经能够:
- 使用
qdrant-store工具存储带有描述的代码片段。 - 使用
qdrant-find工具通过自然语言搜索相关代码片段。
在开发模式下运行 MCP 服务器
可以使用 mcp dev 命令在开发模式下运行 MCP 服务器。该命令会启动服务器,并在浏览器中打开 MCP 检查器。
COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py
与 VS Code 配合使用
如需一键安装,请点击以下任一安装按钮:
手动安装
将以下 JSON 代码块添加到 VS Code 的用户设置 (JSON) 文件中。你可以按 Ctrl + Shift + P 并输入 Preferences: Open User Settings (JSON) 来完成此操作。
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
}
或者,如果你更喜欢使用 Docker,请改为添加以下配置:
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "docker",
"args": [
"run",
"-p", "8000:8000",
"-i",
"--rm",
"-e", "QDRANT_URL",
"-e", "QDRANT_API_KEY",
"-e", "COLLECTION_NAME",
"mcp-server-qdrant"
],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
}
你也可以在工作区中创建一个 .vscode/mcp.json 文件,并添加以下内容:
{
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "uvx",
"args": ["mcp-server-qdrant"],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
对于使用 Docker 的工作区配置,请在 .vscode/mcp.json 中使用以下内容:
{
"inputs": [
{
"type": "promptString",
"id": "qdrantUrl",
"description": "Qdrant URL"
},
{
"type": "promptString",
"id": "qdrantApiKey",
"description": "Qdrant API Key",
"password": true
},
{
"type": "promptString",
"id": "collectionName",
"description": "Collection Name"
}
],
"servers": {
"qdrant": {
"command": "docker",
"args": [
"run",
"-p", "8000:8000",
"-i",
"--rm",
"-e", "QDRANT_URL",
"-e", "QDRANT_API_KEY",
"-e", "COLLECTION_NAME",
"mcp-server-qdrant"
],
"env": {
"QDRANT_URL": "${input:qdrantUrl}",
"QDRANT_API_KEY": "${input:qdrantApiKey}",
"COLLECTION_NAME": "${input:collectionName}"
}
}
}
}
贡献
如果你对如何改进 mcp-server-qdrant 有建议,或想报告错误,请提交 issue! 我们欢迎所有贡献。
在本地测试 mcp-server-qdrant
MCP 检查器 是用于测试和调试 MCP 服务器的开发者工具。它会同时运行客户端 UI(默认端口 5173)和 MCP 代理服务器(默认端口 3000)。在浏览器中打开客户端 UI 即可使用检查器。
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
启动后,在浏览器中打开 http://localhost:5173 以访问检查器界面。
许可证
此 MCP 服务器采用 Apache License 2.0 许可。这意味着你可以自由使用、修改和分发该软件,但须遵守 Apache License 2.0 的条款和条件。详情请参阅项目仓库中的 LICENSE 文件。