1. 为什么要在 Claude Code 里挂一个 Chroma MCP项目文档一多最直接的问题不是“模型不够聪明”而是“它每次都要把整份资料重新读一遍”。我试过把几十个 Markdown 一次性塞进上下文结果就是 token 消耗飞快回答还容易抓不住重点。后来换了个思路让 Claude Code 在需要的时候自己去向量库里捞相关片段而不是把全部内容硬塞给它。Chroma 就是干这个的。它是个轻量向量数据库你可以把它理解成一个“按意思找东西”的仓库。传统数据库你搜“苹果”它只给你带“苹果”这两个字的记录而向量库你给它“苹果”它能把“手机”“水果”“iPhone”这些语义相近的内容一起联想出来。做本地知识库检索、代码片段召回、文档问答这套组合特别顺手。而 MCPModel Context Protocol是 Claude Code 用来对接外部工具的协议。Chroma 官方提供了chroma-mcp这个服务端通过uvx就能拉起不需要你手动先跑一个chroma run。也就是说Claude Code 启动时自动把 Chroma 服务带起来你只管用。这篇就按“能跑通”的标准来先给配置骨架再演示启动、连通性检查最后做一次真实的向量写入和查询验证。适合已经在用 Claude Code、想给本地知识库加检索能力的人。2. 前置准备TaoToken 接入与 uvx 环境Claude Code 要调用模型得先有一个可用的 API 入口。我用的是 TaoToken它的接口兼容主流格式配置起来不折腾。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。第一步去控制台拿 Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面创建一个新 Key复制出来。这个 Key 后面要写进 Claude Code 的环境变量里。第二步确认uvx可用。uvx是 uv 工具链里的命令用来直接运行 Python 包不用先 pip install。检查一下uvx --version如果没有装 uvcurl -LsSf https://astral.sh/uv/install.sh | sh source ~/.bashrc uvx --version第三步确认 Claude Code 已经装好并能正常对话。如果你还没配模型入口可以在 Claude Code 的配置里指定 TaoToken 的 API 地址和 Key。模型对话相关的入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以先在那里确认模型可用。注意uvx第一次运行chroma-mcp时会自动下载依赖网络慢的话会卡一会儿属正常现象。3. 可复制的 MCP 配置骨架Chroma MCP 的接入方式有两种一种是让uvx自己拉起一个持久化服务另一种是连到你已经跑着的 Chroma 实例。这里推荐第一种省事。3.1 用 claude mcp add 一条命令接入最直接的方式是用 Claude Code 自带的命令claude mcp add chroma -- uvx chroma-mcp --client-type persistent --data-dir /root/chroma-database拆开看这几个参数参数作用chromaMCP 服务在 Claude Code 里的名字后面调用时用它uvx chroma-mcp用 uvx 拉起 Chroma MCP 服务端--client-type persistent使用持久化客户端数据落盘不丢--data-dir /root/chroma-database向量数据存放目录按你实际路径改这条命令执行完Claude Code 的 MCP 列表里就会多一个chroma。它不需要你手动先跑chroma run --host 0.0.0.0 --port 8000uvx会在需要时把服务带起来。3.2 settings.json 片段写法如果你习惯直接改配置文件可以在 Claude Code 的settings.json里加一段。路径通常在~/.claude/settings.json或项目级的.claude/settings.json{ mcpServers: { chroma: { command: uvx, args: [ chroma-mcp, --client-type, persistent, --data-dir, /root/chroma-database ] } } }保存后重启 Claude Code它会读取这个配置并注册服务。两种方式选一种就行别重复加否则会出现同名服务冲突。3.3 数据目录要先建好--data-dir指向的目录如果不存在持久化客户端可能报错。先建一下mkdir -p /root/chroma-database权限也要对确保当前用户能读写。如果你是用 root 跑的一般没问题如果是普通用户把路径换成~/chroma-database更稳妥。4. 启动服务与连通性验证配置加完先确认 Claude Code 能识别到这个 MCP 服务。4.1 查看 MCP 列表claude mcp list正常输出里应该能看到chroma状态是 connected 或类似字样。如果显示 failed多半是uvx路径不对或者依赖没下下来。4.2 手动跑一次服务端看日志想排查问题可以脱离 Claude Code 单独跑一次uvx chroma-mcp --client-type persistent --data-dir /root/chroma-database第一次运行会看到它下载chroma-mcp相关包然后进入等待状态。这时候它其实是在等 MCP 客户端通过标准输入输出发指令。你按 CtrlC 退出即可这一步只是确认包能正常拉起。4.3 在 Claude Code 里做一次连通性检查打开 Claude Code直接问它列出当前可用的 MCP 工具如果 chroma 接入成功它会返回一组工具通常包括创建集合、写入文档、查询相似内容这几类。看到这些工具名说明链路通了。提示如果工具列表里没有 chroma先检查claude mcp list的状态再看~/.claude/logs下的日志常见原因是uvx不在 PATH 里。5. 一次向量写入与查询的完整验证光看到工具还不够得实际写一条数据再查出来才算真跑通。5.1 写入一条向量数据在 Claude Code 里让它执行用 chroma 创建一个名为 knowledge 的集合然后写入一条文档 id 为 doc1内容为“Claude Code 可以通过 MCP 接入向量数据库做本地检索”Claude Code 会调用 chroma 的创建集合和写入工具。执行完它会告诉你写入成功。这一步背后其实是把文本转成向量存进了/root/chroma-database。5.2 查询相似内容接着做检索验证在 knowledge 集合里查询“怎么让 Claude Code 做本地知识库检索”返回最相似的 3 条如果写入成功返回结果里应该能看到刚才那条doc1的内容。哪怕你的查询词和原文不完全一样向量检索也能把它捞出来这就是语义匹配的价值。5.3 用命令行直接验证数据落盘想确认数据真的存下来了可以看目录ls -lh /root/chroma-database持久化模式下会生成 sqlite 文件和索引目录。数据在说明--client-type persistent生效了。如果换回内存模式重启后数据就没了所以做知识库一定要用 persistent。5.4 批量写入的写法单条验证通过后实际用的时候通常是批量灌文档。你可以让 Claude Code 读取本地某个目录下的 Markdown逐条写入读取 /root/docs 下所有 .md 文件把每个文件内容作为一条文档写入 knowledge 集合id 用文件名这样一次就能把整个文档库建起来。之后每次提问Claude Code 先检索再回答token 消耗会明显下降。6. 本篇常见错误排查接入过程里踩过的坑基本集中在这几个地方。uvx 找不到报command not found: uvx。原因是 uv 装了但没进 PATH。执行source ~/.bashrc或把~/.local/bin加进 PATH。服务启动超时第一次uvx chroma-mcp要下载依赖网络慢会卡住。可以先手动跑一次让它把包缓存下来再交给 Claude Code。数据目录权限拒绝--data-dir指向的目录当前用户没写权限。换成用户主目录下的路径或者chmod一下。同名服务冲突既用claude mcp add又改了settings.json导致 chroma 注册两次。删掉其中一个用claude mcp remove chroma清理。查询返回空集合名写错或者写入和查询用的不是同一个--data-dir。确认两次操作指向同一个数据目录。client-type 选错用了内存模式重启后数据丢失。知识库场景固定用persistent。如果排查完还是连不上可以去接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 对照接口配置或者到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新生成一个 Key 试试排除鉴权问题。7. 接下来怎么用得更顺链路跑通后真正提升效率的是把检索嵌进日常编码流程。比如你在 Claude Code 里做代码补全或重构时让它先查一遍项目里的历史实现再给建议比凭空生成靠谱得多。长期做编码和 Agent 任务的话可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 配合向量检索把项目上下文管起来。另外一个小技巧文档写入时带上来源路径作为 metadata查询时就能知道答案出自哪个文件方便回溯。Chroma 的 metadata 字段支持这个写入时多传一个source就行。这样检索结果不只是“像”还能“有据可查”。