mcp-server-qdrant：把向量库接进 MCP 客户端的那一层

它解决的是 MCP 客户端没有记忆这件事

LLM 客户端本身不保存跨会话的上下文。你在 Cursor 里让模型记住某个项目的约定，下一次开窗口它就不记得了。要解决这个问题，客户端需要一种标准方式去调用外部存储，而 MCP 就是那个标准接口。这个仓库做的事情很具体：把 Qdrant 包装成一个 MCP 服务器，对外暴露存储与检索两个能力，让任何支持 MCP 的客户端都能把它当成一个可调用的工具集。README 里的定位写得很直白，它充当 Qdrant 数据库之上的语义记忆层。目标用户是已经在用 Qdrant、或者愿意起一个 Qdrant 实例的开发者，而不是想要一个开箱即用的托管记忆服务的人。仓库本身被描述为一个 MCP 服务器的示例实现，这句话值得留意，它暗示了工具面的克制是有意为之。

两个工具，一条从文本到向量的路径

服务器对外只有两个工具。qdrant-store 接收三个输入：information 字符串、可选的 metadata JSON、以及 collection_name。qdrant-find 接收 query 字符串和 collection_name。collection_name 的行为有个细节：如果没有配置默认集合名，这个字段就是必填的；如果配置了 COLLECTION_NAME，这个字段在工具定义里就不启用。这意味着默认集合和显式指定集合是互斥的两种用法，不能混着来。数据流大致是：information 先经过嵌入模型转成向量，连同 metadata 一起写入 Qdrant 集合；检索时 query 走同一个嵌入模型，在集合里做向量相似度搜索，返回若干条结果作为独立消息。搜索返回条数由 QDRANT_SEARCH_LIMIT 控制，默认 10。这里有个容易被忽略的约束：写入和检索必须用同一个嵌入模型，否则向量空间不对齐，检索结果没有意义。

环境变量就是全部配置面

README 明确说配置通过环境变量完成，唯一的命令行参数是 --transport。连接方式有两条路：QDRANT_URL 指向一个 Qdrant 服务，或者 QDRANT_LOCAL_PATH 指向本地数据库路径。文档用醒目提示说明这两者不能同时提供，选一个。如果服务端开了鉴权，用 QDRANT_API_KEY。嵌入相关的两个键是 EMBEDDING_PROVIDER 和 EMBEDDING_MODEL，前者目前只支持 fastembed，后者默认是 sentence-transformers/all-MiniLM-L6-v2。工具描述可以用 TOOL_STORE_DESCRIPTION 和 TOOL_FIND_DESCRIPTION 覆盖，默认值在 src/mcp_server_qdrant/settings.py 里。QDRANT_READ_ONLY 设为 true 会直接禁用 qdrant-store，只保留检索。因为底层是 FastMCP，它还继承了 FASTMCP_ 前缀的一批变量，其中 FASTMCP_LOG_LEVEL 和 FASTMCP_SERVER_PORT 在排查问题时最常用。

启动命令与传输协议的取舍

官方给出的最短路径是用 uvx 直接跑，不需要预先安装。README 的例子是设置 QDRANT_URL、COLLECTION_NAME 和 EMBEDDING_MODEL 三个变量后执行 uvx mcp-server-qdrant。传输协议由 --transport 决定，默认 stdio，只适合本地 MCP 客户端；sse 和 streamable-http 面向远程客户端，后者比前者更新。文档对 sse 的描述是服务器会监听指定端口等待连接，端口默认 8000，可以用 FASTMCP_SERVER_PORT 改。这里的选择不是纯偏好问题：stdio 模式下服务器进程由客户端拉起，生命周期跟着客户端走；换成 sse 或 streamable-http 就变成一个常驻服务，多个客户端可以连同一个实例，但你要自己负责它的进程管理和端口暴露。如果只是本机单人使用，stdio 更省事，也少一个对外监听面。

嵌入模型被锁在 fastembed 是最大的硬约束

EMBEDDING_PROVIDER 的说明里写着 currently only fastembed is supported。这不是文档写得含糊，而是一个明确的能力边界。后果有两层。第一，如果你的组织已经有一套嵌入服务（自建推理、云厂商 API 或某个内部模型），这个服务器接不上去，你要么改成用 fastembed 的本地模型，要么自己改代码。第二，换 EMBEDDING_MODEL 不等于可以随便换：集合的向量维度由模型决定，改了模型就得换集合或者重建索引，而工具面里没有任何重建或迁移的入口。另外需要注意，fastembed 意味着嵌入计算发生在服务器进程本地，第一次运行某个模型时会涉及模型权重的下载，这一点 README 没有展开说明，实际部署时网络与磁盘要留出余量。

写入没有去重，检索没有过滤

从工具定义看，qdrant-store 每次调用就是一条写入，返回的是一句确认消息。文档里没有提到任何去重、覆盖或更新的语义，也没有暴露按 ID 操作的能力。这意味着重复存同一段信息会在集合里留下多条近似记录，而 qdrant-find 返回的又是若干条独立消息，长期使用后检索结果里出现冗余的概率会上升。metadata 是可选写入的，但 qdrant-find 的输入只有 query 和 collection_name，没有过滤参数，所以写进去的 metadata 在当前工具面下无法用于检索阶段的筛选。如果你需要按用户、按项目或按时间范围限定检索，这个服务器给不了，得直接在 Qdrant 侧做或者改代码。这两点合起来说明它的定位偏向轻量的个人记忆，而不是多租户的知识库。

什么时候该换成直接写 Qdrant 客户端

一个现实的替代方案是跳过 MCP 这一层，在应用里直接用 Qdrant 的 Python 客户端。差别在于控制粒度：直接调客户端时，嵌入用哪个模型、向量写进哪个命名空间、检索时带什么 filter、结果怎么排序和截断，全部由你决定；代价是你要自己实现工具定义和 MCP 协议对接，客户端那边也不会自动把它识别成可用工具。反过来，这个服务器的全部价值就在于它已经把那层协议适配做完了，你只需要给几个环境变量。判断标准很清楚：如果你的检索需求能用一个 query 字符串加固定集合表达，用这个服务器；如果需要过滤、需要自定义嵌入、需要更新和删除，直接写客户端更省事，因为绕过它之后你要补的功能比它提供的还多。

版本、许可与需要先验证的事

最近几个版本是 v0.8.1、v0.8.0 和 v0.7.1，时间跨度从 2025 年 3 月到 12 月，节奏不算密集。README 里有一条提示值得记下来：服务器专属设置使用 FASTMCP_SERVER_ 前缀，并且这个约定在未来版本可能变化。也就是说升级时这类变量名属于需要复查的部分。许可证是 Apache-2.0，允许商用和修改，具体义务以仓库中的 LICENSE 文件为准，这里不做法律判断。上手前建议按顺序验证：先用 QDRANT_URL 或 QDRANT_LOCAL_PATH 确认能连上实例，再确认目标集合存在且维度与 EMBEDDING_MODEL 一致，然后手动调一次 qdrant-store 和 qdrant-find 看返回是否符合预期，最后再决定要不要用 QDRANT_READ_ONLY 把写入关掉。

编辑结论

如果你已经在跑 Qdrant，只想让 Claude、Cursor 或 Windsurf 这类 MCP 客户端能存一段文字、再按语义找回来，这个服务器是够用的，配置基本就是 QDRANT_URL、COLLECTION_NAME 加一个嵌入模型名。如果你需要自定义嵌入服务、需要按 metadata 做过滤检索、或者需要更新与删除已写入的记忆，它就不合适，因为工具面只有 store 和 find 两个，EMBEDDING_PROVIDER 目前也只支持 fastembed。动手前先确认三件事：Qdrant 实例是否可达（本地模式用 QDRANT_LOCAL_PATH，注意它和 QDRANT_URL 不能同时给）、目标集合是否已经存在且维度与所选 EMBEDDING_MODEL 匹配、以及是否需要设 QDRANT_READ_ONLY 来关掉写入工具。

官方来源

1. License: Apache-2.0
2. Project website
3. qdrant/mcp-server-qdrant on GitHub
4. README
5. Releases