mcp-server-qdrant

环境要求

• 一个可访问的 Qdrant 实例（云端 URL 或本地数据库路径）
• 支持 MCP 的客户端：Claude Desktop、VS Code 或 Cursor 等
• 使用 uvx/Docker/Smithery 之一作为运行方式（uvx 与 Docker 需已安装）
• Qdrant 云服务需准备 API Key 与集群地址（形如 https://xyz-example.eu-central.aws.cloud.qdrant.i

安装与启动步骤

1. 1准备 Qdrant 连接信息

   确定目标向量库地址与密钥：云服务用 QDRANT_URL + QDRANT_API_KEY，本地模式改用 QDRANT_LOCAL_PATH 指向数据库目录。

2. 2用 Docker 启动服务

   按需替换地址、密钥和集合名；必须设置 FASTMCP_SERVER_HOST 为 0.0.0.0，容器外才能访问服务。

   docker run -p 8000:8000 -e FASTMCP_SERVER_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

   复制

3. 3用 Smithery 自动安装

   面向 Claude Desktop 的一键安装命令，会写入客户端配置，适合不想手动改 JSON 的用户。

   npx @smithery/cli install mcp-server-qdrant --client claude

   复制

4. 4配置 Claude Desktop

   在 claude_desktop_config.json 的 mcpServers 中加入该项；本地模式则把 QDRANT_URL/QDRANT_API_KEY 换成 QDRANT_LOCAL_PATH。

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

   复制

5. 5配置 VS Code 工作区

   在工作区新建 .vscode/mcp.json，写入 servers 配置；输入项会在启动时提示填写地址、密钥和集合名。

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

   复制

6. 6开发模式调试

   在源码目录用 fastmcp dev 启动服务并自动打开浏览器中的 MCP inspector，便于查看工具调用情况。

   COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

   复制

关键配置

如何确认成功

Docker 容器无报错运行且 8000 端口可访问；或在客户端中让助手调用 qdrant-store 存一条信息、再用 qdrant-find 检索到该内容。

常见问题

注意事项

• QDRANT_API_KEY 属于敏感信息，不要写进公开仓库或共享配置文件。
• Docker 与 uvx 两种方式只需选一种，重复配置同一客户端可能造成冲突。
• 开发模式命令需在项目源码根目录执行，且依赖 fastmcp 已可用。