1. 项目概述为你的LLM应用构建一个专属的语义记忆库如果你正在使用 Claude、Cursor 或 Windsurf 这类 AI 辅助开发工具是否曾有过这样的体验你昨天刚和 AI 讨论过一个复杂的业务逻辑实现今天再问类似的问题时它却像失忆了一样需要你重新解释一遍上下文或者你希望 AI 能记住你项目里那些独特的代码规范、内部 API 的使用方式甚至是团队讨论过的技术决策让这些知识能随时被精准地检索和复用这正是mcp-server-qdrant这个项目要解决的核心痛点。它不是一个独立的应用而是一个桥梁一个基于Model Context Protocol (MCP)的服务器。简单来说MCP 就像是为大型语言模型LLM定义的一套“外接设备”标准协议允许 Claude、Cursor 等客户端安全、标准化地调用外部工具和数据源。而mcp-server-qdrant则是一个具体的“外接设备”——它将强大的向量数据库Qdrant的能力以“记忆存储与检索”工具的形式暴露给你的 AI 助手。你可以把它理解为给你的 AI 伙伴装上了一块“外置硬盘”专门用来存储和查找那些基于语义的、非结构化的“记忆”。无论是代码片段、设计文档、会议纪要还是学习笔记只要转换成文本它都能理解其含义并在你需要时通过自然语言描述精准地找回来。这对于构建具有长期记忆和领域知识深度的 AI 工作流至关重要。接下来我将带你从零开始深入理解并部署这个强大的工具分享我在实际集成和调优中积累的一手经验。2. 核心组件与工作原理深度解析在动手部署之前我们必须先吃透它的核心构成和工作机制。这能帮助你在后续配置和排错时清楚地知道每一个环节在做什么为什么这么做。2.1 MCP 协议LLM 的“万能插槽”MCP 的核心理念是解耦与标准化。在过去每个 AI 应用如 Claude Desktop如果想接入一个新的工具比如日历、数据库都需要进行定制化开发过程繁琐且不通用。MCP 定义了一套标准的通信协议让工具开发者可以编写通用的MCP 服务器而 AI 客户端只需实现 MCP 客户端协议就能无缝接入所有符合标准的工具。mcp-server-qdrant就是一个标准的 MCP 服务器。它启动后会通过stdio标准输入输出、SSE服务器发送事件或Streamable HTTP这些传输协议等待 Claude、Cursor 等客户端来连接。一旦连接建立客户端就能发现这个服务器提供了哪些“工具”Tools并按照协议调用它们。2.2 Qdrant高性能向量搜索引擎Qdrant 是本项目的存储与检索核心。它是一个用 Rust 编写的高性能向量数据库专门为机器学习和 AI 应用设计。与传统数据库通过精确匹配如LIKE查找数据不同向量数据库存储的是数据的“向量嵌入”Embedding并通过计算向量之间的“距离”如余弦相似度来查找语义上最相近的内容。举个例子你存储了一段描述“如何使用 Python 的 requests 库发送 HTTP GET 请求”的文本。它的向量嵌入是一个由数百或数千个维度组成的数学表示。当你查询“用 Python 获取网页内容”时即使字面不完全匹配但由于语义高度相关这两个文本的向量在空间中的位置会很接近Qdrant 就能把它找出来。mcp-server-qdrant在幕后自动完成了文本到向量的转换工作。它使用FastEmbed库来生成嵌入向量默认模型是sentence-transformers/all-MiniLM-L6-v2这是一个在通用文本上表现良好且速度较快的轻量级模型。2.3 两大核心工具qdrant-store与qdrant-find服务器向客户端暴露了两个核心工具这也是我们与之交互的全部接口qdrant-store(存储工具)功能将一段信息及其元数据存入 Qdrant 数据库。输入参数information(字符串)需要存储的核心文本内容。例如“用户登录功能的实现包含 JWT 令牌生成和验证。”metadata(JSON 对象可选)任何你想附加的结构化信息。这是存储代码、链接等内容的绝佳位置。例如{code: def login(user): ..., file: auth.py, language: python}。collection_name(字符串条件必填)指定存储到 Qdrant 的哪个集合类似数据库的表。如果环境变量中设置了COLLECTION_NAME则此参数可选否则必填。输出简单的确认消息如“信息已成功存储”。qdrant-find(查找工具)功能根据自然语言查询从 Qdrant 数据库中检索最相关的信息。输入参数query(字符串)你的搜索问题。例如“怎么实现用户认证”collection_name(字符串条件必填)指定从哪个集合检索。规则同qdrant-store。输出返回一组最相关的存储信息每条信息都包含原始的information文本和metadata。注意collection_name参数的设计体现了灵活性。通过环境变量设置默认集合适合单一用途的场景如“个人代码库”。而在工具调用时动态指定集合名则适合多租户或项目隔离的场景如“project_a_docs”, “project_b_snippets”。2.4 数据流转全景图为了让你更直观地理解整个过程我们来看一个从存储到检索的完整数据流sequenceDiagram participant User as 用户/AI助手 participant Client as MCP客户端(Claude/Cursor) participant Server as mcp-server-qdrant participant Embed as FastEmbed模型 participant DB as Qdrant数据库 Note over User,DB: 存储阶段 (qdrant-store) User-Client: 输入“保存这段代码br/登录函数用JWT” Client-Server: 调用工具 qdrant-storebr/information“登录函数...”br/metadata{“code”: “def login():...”} Server-Embed: 将 information 文本转换为向量 Embed--Server: 返回向量 [0.1, 0.5, ...] Server-DB: 存储向量 原始文本 metadata DB--Server: 存储成功 Server--Client: 返回“信息已存储” Client--User: 操作完成确认 Note over User,DB: 检索阶段 (qdrant-find) User-Client: 输入“怎么验证用户身份” Client-Server: 调用工具 qdrant-findbr/query“怎么验证用户身份” Server-Embed: 将 query 文本转换为向量 Embed--Server: 返回查询向量 [0.12, 0.48, ...] Server-DB: 执行向量相似度搜索 DB--Server: 返回最相似的几条记录br/(含之前存储的文本和metadata) Server--Client: 返回检索结果 Client--User: 展示“找到相关代码登录函数...”这个流程揭示了几个关键点首先语义搜索的核心在于向量化无论是存储还是查询文本都需经过同一个嵌入模型转换确保它们在同一个向量空间内可比。其次Qdrant 执行的是近似最近邻搜索它不会遍历所有数据而是用高效算法快速找到最相似的几个结果。最后返回给用户的是原始的、可读的文本和元数据这使得 AI 助手能直接理解和利用这些信息。3. 环境配置与部署实战理解了原理我们进入实战环节。部署mcp-server-qdrant有多种方式我将逐一详解并分享我的选型建议和避坑经验。3.1 前置条件准备 Qdrant无论采用哪种部署方式你都需要一个可用的 Qdrant 服务。你有三个主流选择本地 Docker 运行推荐用于开发测试docker run -p 6333:6333 -p 6334:6334 \ -v $(pwd)/qdrant_storage:/qdrant/storage:z \ qdrant/qdrant这会在本地启动 Qdrant数据将持久化到当前目录的qdrant_storage文件夹。访问http://localhost:6333/dashboard可以打开管理界面。Qdrant Cloud推荐用于生产或团队共享前往 Qdrant Cloud 注册并创建一个集群。创建后会获得一个URL如https://xyz-123.us-east-1-0.aws.cloud.qdrant.io:6333和一个API Key。请妥善保存。使用本地文件模式极简测试这是mcp-server-qdrant提供的一个便利特性通过设置QDRANT_LOCAL_PATH环境变量如./my_qdrant_data服务器会使用 Qdrant 的嵌入式模式无需单独运行 Qdrant 服务。注意此模式功能可能受限且QDRANT_LOCAL_PATH和QDRANT_URL不能同时设置。3.2 部署方式一使用 uvx最灵活uvx是新兴的 Python 包运行器类似于npx。它无需安装即可直接运行 PyPI 上的包非常适合快速尝试。基础启动命令QDRANT_URLhttp://localhost:6333 \ COLLECTION_NAMEmy_memories \ EMBEDDING_MODELsentence-transformers/all-MiniLM-L6-v2 \ uvx mcp-server-qdrant这条命令会使用默认的stdio传输协议启动服务器适合与本地桌面客户端如 Claude Desktop直接通信。选择传输协议--transport stdio默认。通过标准输入输出与客户端通信只能用于和服务器在同一台机器上启动的客户端。--transport sse使用 Server-Sent Events。服务器会启动一个 HTTP 服务默认端口 8000等待远程连接。这是与 Cursor/Windsurf 等 IDE 插件连接的首选方式因为它支持远程主机。QDRANT_URLhttp://localhost:6333 \ COLLECTION_NAMEmy_memories \ FASTMCP_PORT8080 \ # 可以自定义端口 uvx mcp-server-qdrant --transport sse--transport streamable-http更新的 HTTP 流式传输协议比 SSE 更现代。实操心得在团队协作场景下我强烈推荐使用SSE 协议。你可以在某台内网服务器上部署mcp-server-qdrant并暴露 SSE 端口团队所有成员的 Cursor 都可以配置连接到这个统一的服务器地址共享同一个知识库。这避免了每个人都在本地维护一套重复的数据。3.3 部署方式二使用 Docker便于部署与管理项目提供了 Dockerfile适合在容器化环境中运行。构建与运行# 1. 克隆代码并构建镜像 git clone https://github.com/qdrant/mcp-server-qdrant.git cd mcp-server-qdrant docker build -t mcp-server-qdrant . # 2. 运行容器 docker run -d --name qdrant-mcp \ -p 8000:8000 \ # 映射 SSE 服务端口 -e FASTMCP_HOST0.0.0.0 \ # 关键让服务监听所有网络接口 -e FASTMCP_PORT8000 \ -e QDRANT_URLhttps://your-cloud-cluster.cloud.qdrant.io:6333 \ -e QDRANT_API_KEYyour-api-key-here \ -e COLLECTION_NAMEteam_knowledge_base \ mcp-server-qdrant --transport sse关键点在 Docker 中运行必须设置FASTMCP_HOST0.0.0.0否则服务只会绑定到容器内部的127.0.0.1导致外部无法访问。3.4 部署方式三配置到具体客户端服务器部署好后需要配置到你的 AI 客户端才能使用。1. 配置 Claude Desktop 找到 Claude Desktop 的配置文件macOS:~/Library/Application Support/Claude/claude_desktop_config.json Windows:%APPDATA%\Claude\claude_desktop_config.json在mcpServers部分添加{ mcpServers: { qdrant: { command: uvx, args: [mcp-server-qdrant], env: { QDRANT_URL: http://localhost:6333, COLLECTION_NAME: claude_memories, EMBEDDING_MODEL: BAAI/bge-small-en-v1.5 // 可选更换为其他FastEmbed模型 } } } }保存后重启 Claude Desktop在聊天界面你应该能看到新增的工具图标。2. 配置 Cursor / Windsurf 由于 Cursor 通常作为独立应用运行使用 SSE 连接是更可靠的方式。首先确保mcp-server-qdrant以 SSE 模式运行。然后在 Cursor 中打开设置搜索 “MCP”添加一个新的 MCP 服务器。名称任意如My Qdrant Memory。类型选择sse。URL填写http://localhost:8000/sse如果你的服务器运行在其他机器或端口请相应修改。3. 配置 VS Code VS Code 的配置最为灵活支持通过settings.json或工作区.vscode/mcp.json文件配置。以下是全局配置示例CtrlShiftP-Preferences: Open User Settings (JSON){ mcp: { servers: { qdrant: { command: uvx, args: [mcp-server-qdrant], env: { QDRANT_URL: http://localhost:6333, COLLECTION_NAME: vscode_context } } } } }我更推荐使用工作区配置.vscode/mcp.json这样配置可以随项目代码一起共享给团队成员。4. 高级用法与场景定制基础部署只是开始mcp-server-qdrant的真正威力在于根据你的特定场景进行定制。4.1 打造专属的智能代码助手这是我认为最具价值的应用场景。通过定制工具描述你可以引导 AI 如何更好地使用这个记忆库。场景你希望 AI 将写过的优质代码片段存储起来并在后续编码时智能推荐。配置方案# 启动服务器时覆盖默认的工具描述 QDRANT_URLhttp://localhost:6333 \ COLLECTION_NAMEcode_snippets_lib \ TOOL_STORE_DESCRIPTION存储可复用的代码片段以备后用。information 参数应包含代码功能的自然语言描述例如使用Python Pandas读取CSV并计算某列的平均值而实际的代码内容应放在 metadata 参数的 code 字段中。metadata 是一个Python字典。当你生成一些有价值的、通用的或复杂的代码片段时请使用此工具将其保存。 \ TOOL_FIND_DESCRIPTION基于自然语言描述搜索相关的代码片段。query 参数应描述你想要实现的功能例如如何用pandas合并两个表格工具将返回最相关的代码片段。当你在编写代码时需要参考或复用现有实现时请使用此工具。 \ uvx mcp-server-qdrant --transport sse效果当你让 AI 写一个“快速排序算法”时AI 在生成代码后可能会主动调用qdrant-store将其保存。几天后当你询问“怎么实现一个高效的排序函数”时AI 会调用qdrant-find快速找到之前存储的快速排序代码并提供给你。4.2 管理项目文档与决策记录场景在大型项目中架构决策、API 设计文档、故障排查记录分散各处难以查找。配置方案你可以创建另一个集合专门用于存储文档。# 可以运行另一个服务器实例使用不同的端口和集合名 QDRANT_URLhttp://localhost:6333 \ COLLECTION_NAMEproject_docs \ TOOL_STORE_DESCRIPTION存储项目相关的文档片段、架构决策或会议纪要。information 是内容的简要总结metadata 中可以包含详细内容、相关链接links、负责人owner和标签tags。 \ TOOL_FIND_DESCRIPTION在全项目文档中搜索相关信息。根据问题描述查找相关的设计决策、技术方案或历史记录。 \ FASTMCP_PORT8001 \ uvx mcp-server-qdrant --transport sse这样在项目讨论中你可以让 AI 帮你记录“保存本次关于数据库选型的结论”并在后续需要时直接提问“我们当初为什么决定用 PostgreSQL 而不是 MySQL”AI 就能从记忆库中找出当时的讨论记录。4.3 嵌入模型的选择与优化默认的all-MiniLM-L6-v2模型通用性好且速度快。但针对特定领域更换模型可能大幅提升效果。mcp-server-qdrant支持所有 FastEmbed 提供的模型 。代码搜索优化可以尝试BAAI/bge-base-en-v1.5或专门针对代码训练的模型需确认 FastEmbed 是否支持。多语言支持如果你的内容包含中文可以使用BAAI/bge-small-zh-v1.5。性能与精度权衡*-small-*系列模型速度最快*-base-*和*-large-*精度更高但更耗资源。对于大多数应用bge-small-*系列是很好的起点。更换模型只需设置EMBEDDING_MODEL环境变量并确保新集合使用新模型。因为不同模型生成的向量维度可能不同不能混用。如果更换模型最好也更换一个COLLECTION_NAME或清空原有集合。5. 常见问题排查与实战技巧在实际使用中你可能会遇到一些问题。这里我总结了一份排查清单和技巧。5.1 连接与配置问题问题现象可能原因解决方案Claude Desktop 中看不到工具1. 配置文件路径错误。2. 环境变量未生效。3.uvx命令执行失败。1. 确认配置文件路径正确JSON 格式无误。2. 尝试在命令行直接运行uvx mcp-server-qdrant看是否有报错如缺少依赖。3. 重启 Claude Desktop。Cursor/VS Code 连接失败 (SSE)1. 服务器未以 SSE 模式启动。2. 防火墙/端口阻止。3. 客户端 URL 配置错误。1. 确认启动命令包含--transport sse。2. 用curl http://localhost:8000/sse测试服务器是否可达。3. 检查客户端配置的 URL 是否为http://服务器IP:端口/sse。工具调用返回“集合不存在”错误1. 指定的collection_name在 Qdrant 中不存在。2. 环境变量COLLECTION_NAME未设置且调用时也未提供。1. 服务器会在第一次存储时自动创建集合请先尝试调用一次qdrant-store。2. 确保在环境变量或工具调用参数中提供了有效的集合名。存储或查询速度慢1. 嵌入模型过大。2. Qdrant 服务器资源不足或网络延迟高。3. 集合中文档数量巨大。1. 换用*-small-*模型。2. 检查 Qdrant 服务器状态考虑升级配置或使用本地部署。3. 确保 Qdrant 已建立向量索引服务器会自动处理。5.2 效果优化技巧存储内容的“信息密度”information字段应包含核心的、可检索的语义信息。避免存储过于冗长或包含大量无关细节的文本。好的例子“使用 asyncio 和 aiohttp 实现高并发 HTTP 请求爬虫”。坏的例子“今天下午我写了一个爬虫用了 asyncio还喝了杯咖啡...”。善用metadata这是结构化信息的宝地。除了存储代码code: ...还可以添加file_path、language、project、tags: [backend, auth]等。未来如果工具支持过滤查询这些元数据将极其有用。查询的艺术检索效果取决于查询词与存储内容在语义上的匹配度。多尝试用不同的方式描述你的需求。例如想找“错误处理”的代码除了“error handling”也可以试“exception”、“try catch”、“how to handle failures”。集合规划不要把所有东西都塞进一个集合。按领域、项目或类型分开存储如frontend_snippets,backend_apis,devops_scripts。这能提高检索精度也便于管理。数据预热与维护初期可以手动或写脚本批量导入一批高质量的种子数据如项目核心工具函数、架构说明。定期检查存储的内容对于低质量或过时的条目可以考虑通过 Qdrant 的 API 直接删除。5.3 开发与调试如果你想基于此项目进行二次开发或者排查深层次问题启用开发模式COLLECTION_NAMEtest fastmcp dev src/mcp_server_qdrant/server.py这会启动服务器并打开 MCP Inspector (通常为http://localhost:5173)这是一个图形化界面可以实时查看工具调用、请求和响应是调试的利器。查看日志设置环境变量FASTMCP_LOG_LEVELDEBUG可以输出详细的调试日志帮助你了解内部执行过程。理解代码结构项目核心逻辑在src/mcp_server_qdrant/server.py中。工具的定义在src/mcp_server_qdrant/tools/目录下。如果你想添加新的工具比如按 metadata 过滤的查找工具可以在这里进行扩展。6. 安全、成本与扩展性考量将这样一个语义记忆库集成到日常工作流中还需要考虑一些工程化问题。安全性API Key 管理切勿将 Qdrant Cloud 的 API Key 硬编码在配置文件或命令行中。使用环境变量或客户端提供的安全输入机制如 VS Code 的inputs。网络暴露以 SSE 模式运行并暴露端口时确保有适当的防火墙规则不要将服务直接暴露在公网。考虑增加基本的 HTTP 认证或将其部署在内网。数据隐私存储的内容可能包含敏感信息代码、内部文档。确保你使用的 Qdrant 实例无论是自建还是云服务符合你的数据安全要求。成本Qdrant Cloud有免费额度超出后按使用量计费。主要成本来自存储的向量数量和查询次数。计算资源嵌入模型推理尤其是大型模型和向量搜索会消耗 CPU/内存。对于个人使用本地运行压力不大对于团队服务需要监控服务器负载。优化建议对于非实时或低频访问的冷数据可以考虑定期归档导出向量数据需要时再导入以节省云服务成本。扩展性性能Qdrant 本身具有良好的水平扩展能力。如果检索速度随着数据量增长而下降可以考虑在 Qdrant 中配置更高效的索引如 HNSW或增加副本。功能扩展当前的qdrant-find是纯语义搜索。一个常见的扩展需求是“混合搜索”即结合关键词如 metadata 中的 tag和向量语义进行检索。这需要修改服务器代码利用 Qdrant 的过滤搜索功能。多模态未来虽然当前版本只处理文本但 Qdrant 支持存储多模态向量如图像、音频。理论上可以扩展此服务器使其也能存储和检索图片描述、音频摘要等为 AI 助手提供更丰富的上下文。从我个人的使用体验来看mcp-server-qdrant最迷人的地方在于它以一种轻巧、标准化的方式将强大的向量检索能力赋予了日常使用的 AI 工具。它可能不会每次都完美地找到你想要的内容但一旦你养成了让 AI 随时存储重要信息的习惯并在需要时自然地询问你会发现它逐渐成为了一个不可或缺的“第二大脑”。开始的最佳方式就是选一个你正在进行的项目配置好服务器然后告诉你的 AI 助手“记住这个我们以后可能会用到。”