mcp-server-qdrant：Qdrant MCP 服务器
模型上下文协议 (MCP)是一种开放协议，支持 LLM 应用程序与外部数据源和工具之间的无缝集成。无论您是构建 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都提供了一种标准化的方式，将 LLM 与其所需的上下文连接起来。
该存储库是如何为矢量搜索引擎Qdrant创建 MCP 服务器的示例。
概述
官方模型上下文协议服务器，用于在 Qdrant 矢量搜索引擎中保存和检索记忆。它充当 Qdrant 数据库之上的语义记忆层。
成分
工具
qdrant-store- 在 Qdrant 数据库中存储一些信息
- 输入：
information （字符串）：要存储的信息metadata （JSON）：可选存储元数据collection_name （字符串）：用于存储信息的集合名称。如果没有默认集合名称，则此字段为必填项。如果存在默认集合名称，则此字段不启用。
- 返回：确认消息
qdrant-find- 从 Qdrant 数据库中检索相关信息
- 输入：
query （字符串）：用于搜索的查询collection_name （字符串）：用于存储信息的集合名称。如果没有默认集合名称，则此字段为必填项。如果存在默认集合名称，则此字段不启用。
- 返回：作为单独消息存储在 Qdrant 数据库中的信息
环境变量
服务器的配置是使用环境变量完成的：
| 姓名 | 描述 | 默认值 |
|---|
QDRANT_URL | Qdrant 服务器的 URL | 没有任何 |
QDRANT_API_KEY | Qdrant 服务器的 API 密钥 | 没有任何 |
COLLECTION_NAME | 要使用的默认集合的名称。 | 没有任何 |
QDRANT_LOCAL_PATH | 本地 Qdrant 数据库的路径（ QDRANT_URL的替代方法） | 没有任何 |
EMBEDDING_PROVIDER | 要使用的嵌入提供程序（当前仅支持“fastembed”） | fastembed |
EMBEDDING_MODEL | 要使用的嵌入模型的名称 | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | 商店工具的自定义描述 | 请参阅settings.py中的默认值 |
TOOL_FIND_DESCRIPTION | 查找工具的自定义描述 | 请参阅settings.py中的默认值 |
注意：您不能同时提供QDRANT_URL和QDRANT_LOCAL_PATH 。
重要提示：命令行参数不再受支持！请对所有配置使用环境变量。
安装
使用 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 ：服务器发送事件传输，非常适合远程客户端
如果未指定，则默认传输为stdio 。
使用 Docker
Dockerfile 可用于构建和运行 MCP 服务器：
# Build the container
docker build -t mcp-server-qdrant .
# Run the container
docker run -p 8000:8000 \
-e QDRANT_URL="http://your-qdrant-server:6333" \
-e QDRANT_API_KEY="your-api-key" \
-e COLLECTION_NAME="your-collection" \
mcp-server-qdrant
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装 Qdrant MCP 服务器：
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一起使用，它们内置了对模型上下文协议 (MCP) 的支持。
与 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 中，您可以通过使用 SSE 传输协议指向正在运行的 MCP 服务器，从而在设置中配置该服务器。有关如何将 MCP 服务器添加到 Cursor 的说明，请参阅Cursor 文档。如果您在本地运行 Cursor/Windsurf，可以使用以下 URL：
http://localhost:8000/sse
提示：我们建议使用 SSE 传输方式将 Cursor/Windsurf 连接到 MCP 服务器，因为它支持远程连接。这样可以轻松地与您的团队共享服务器或在云环境中使用。
此配置将 Qdrant MCP 服务器转变为专门的代码搜索工具，可以：
- 存储代码片段、文档和实现细节
- 根据语义搜索检索相关代码示例
- 帮助开发人员找到具体的实现或使用模式
您可以通过存储代码片段的自然语言描述（在information参数中）以及实际代码（在metadata.code属性中）来填充数据库，然后使用描述您要查找内容的自然语言查询来搜索它们。
以上提供的工具描述仅为示例，可能需要根据你的具体用例进行自定义。请考虑调整描述，以更好地匹配你团队的工作流程以及你想要存储和检索的特定类型的代码片段。
**如果您已成功安装mcp-server-qdrant ，但仍无法使其与 Cursor 配合使用，请考虑创建Cursor 规则，以便代理生成新的代码片段时始终使用 MCP 工具。**您可以限制规则仅适用于某些文件类型，以避免将 MCP 服务器用于文档或其他类型的内容。
与 Claude 代码一起使用
您可以通过将 Claude Code 连接到此 MCP 服务器来增强其功能，从而对现有代码库进行语义搜索。
设置 mcp-server-qdrant
- 将 MCP 服务器添加到 Claude 代码：
# 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 代码中使用语义代码搜索
TOOL_STORE_DESCRIPTION和TOOL_FIND_DESCRIPTION中指定的工具描述指导 Claude Code 如何使用 MCP 服务器。以上提供的描述仅为示例，可能需要根据您的具体用例进行定制。但是，Claude Code 应该已经能够：
- 使用
qdrant-store工具存储带有描述的代码片段。 - 使用
qdrant-find工具以自然语言搜索相关的代码片段。
在开发模式下运行 MCP 服务器
您可以使用mcp dev命令以开发模式运行 MCP 服务器。这将启动服务器并在浏览器中打开 MCP 检查器。
COLLECTION_NAME=mcp-dev mcp 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 的改进有任何建议，或者想要报告错误，请提交问题！我们期待您的贡献。
在本地测试mcp-server-qdrant
MCP 检查器是一款用于测试和调试 MCP 服务器的开发者工具。它同时运行客户端 UI（默认端口 5173）和 MCP 代理服务器（默认端口 3000）。请在浏览器中打开客户端 UI 即可使用检查器。
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
mcp dev src/mcp_server_qdrant/server.py
启动后，打开浏览器访问http://localhost:5173来访问检查器界面。
执照
此 MCP 服务器遵循 Apache 许可证 2.0 许可。这意味着您可以自由使用、修改和分发该软件，但须遵守 Apache 许可证 2.0 的条款和条件。更多详情，请参阅项目仓库中的 LICENSE 文件。