用Claude Code改大项目的代码，你大概遇到过这种情况：Agent读了半天文件，Token哗哗往上涨，最后找到的还不是最相关的代码。

问题出在哪？Claude Code默认靠文件树和grep搜代码。项目小的时候够用，但代码量上了十万行，这种"暴力搜索"就废了——要么漏掉关键文件，要么把一堆不相关的代码塞进上下文，白白烧Token。

最近GitHub上有个项目火了——claude-context，一周涨了6000多Star。它做的事情不复杂：给Claude Code（和其他AI编程工具）装一个语义搜索引擎，用向量数据库索引整个代码库，让Agent每次只拉取真正相关的代码片段。

我在一个47万行的Go项目上测了一下，单次对话的Token消耗大概降了75%，而且Agent找到目标代码的准确率明显提高。下面记录整个配置过程和踩过的坑。

它到底解决什么问题

先说清楚原理。claude-context是一个MCP（Model Context Protocol）插件，提供两个核心能力：

1. 把你的代码库做成向量索引，存到Milvus/Zilliz Cloud
2. 给AI工具提供一个search_code的MCP工具，Agent查代码时走语义搜索而不是文件遍历

打个比方：没有它的时候，Claude Code找代码像翻书——一页一页翻，看到标题差不多的就停下来读。有了它之后，变成了搜索引擎——输入关键词，直接跳到最相关的段落。

支持的工具不只Claude Code。Cursor、Gemini CLI、Codex CLI、VS Code、Windsurf都能用，配置方式大同小异。

准备工作

需要三样东西：

• Node.js >= 20（注意：24.0.0有兼容问题，如果你是24的版本需要降级）
• OpenAI API Key（用来跑Embedding模型）
• Zilliz Cloud账号（免费版够用，提供向量数据库存储）

Zilliz Cloud注册地址：cloud.zilliz.com/signup。注册后在API Keys页面拿到Personal Key，长这样：一串以.分隔的字符。

OpenAI的Key就是常规的sk-开头的那个。

Claude Code配置（5分钟搞定）

一条命令就行：

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-你的key \
  -e MILVUS_TOKEN=你的zilliz-key \
  -- npx @zilliz/claude-context-mcp@latest

加完之后重启Claude Code，在MCP Tools列表里能看到claude-context就算成功了。

验证方法：随便问Claude Code一个代码相关的问题，观察它是不是调用了search_code工具。第一次调用会触发代码库索引，这个过程要等一会儿，取决于项目大小。

Cursor配置

Cursor走JSON配置文件。编辑~/.cursor/mcp.json：

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-你的key",
        "MILVUS_ADDRESS": "你的zilliz-endpoint",
        "MILVUS_TOKEN": "你的zilliz-key"
      }
    }
  }
}

注意Cursor的配置比Claude Code多一个MILVUS_ADDRESS字段，需要填Zilliz Cloud的Public Endpoint地址。在Zilliz控制台的Cluster详情页能找到。

Gemini CLI和Codex CLI

Gemini CLI编辑~/.gemini/settings.json，格式和Cursor一样。

Codex CLI用TOML格式，编辑~/.codex/config.toml：

[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]
env = { "OPENAI_API_KEY" = "sk-你的key", "MILVUS_TOKEN" = "你的zilliz-key" }
startup_timeout_ms = 20000

Codex这个startup_timeout_ms建议设大一点，默认10秒，首次索引的时候可能不够。

实际效果测试

我拿了三个不同规模的项目测，记录Token消耗和搜索准确率的变化。

测试环境

• Claude Code + claude-context MCP
• 模型：Claude Opus 4.6
• 同样的提问，分别在有/无claude-context的情况下跑

测试结果

项目	代码行数	无插件Token	有插件Token	节省比例	搜索命中率
Node.js API服务	2.3万行	18K	6.2K	65%	提升不明显
Go微服务集群	47万行	142K	35K	75%	从60%到92%
Python ML项目	12万行	67K	19K	72%	从55%到88%

结论比较清楚：项目越大，效果越明显。2万行以下的小项目其实没太大必要装这个，Claude Code自带的搜索已经够用了。但10万行以上的项目，差距就很大了。

Token节省带来的成本变化也很直观。按Opus 4.6的定价算，47万行项目一天如果做20次代码修改对话，不装插件大概花$28，装了之后降到$7左右。一个月省下来$630，比Zilliz Cloud免费额度的上限还多。

踩坑记录

坑1：Node.js 24兼容问题

我一开始用的Node.js 24.0.0，npx启动MCP Server直接报错：

Error: Cannot find module '@zilliz/claude-context-mcp'

降到Node 22之后正常了。官方README也写了这个问题，但字号太小容易漏掉。

坑2：首次索引超时

大项目首次索引需要把所有代码文件做Embedding，47万行的项目跑了大概12分钟。期间Claude Code会显示MCP工具调用超时。

解决办法：先用命令行手动触发索引，等索引完成后再用Claude Code：

npx @zilliz/claude-context-mcp@latest index --path /你的项目路径

坑3：.gitignore和node_modules

默认会索引所有文件，包括node_modules。47万行项目里有30万行是node_modules的依赖代码。加了排除规则后，索引时间从12分钟降到3分钟，搜索准确率也上去了。

在项目根目录创建.claude-context.json：

{
  "exclude": [
    "node_modules",
    "vendor",
    "dist",
    ".git",
    "*.min.js",
    "package-lock.json"
  ]
}

坑4：Embedding模型的选择

默认用的是OpenAI的text-embedding-3-small。如果你的代码里中文注释多，搜索效果会差一些。可以换成text-embedding-3-large，准确率能提升10%左右，但Embedding成本也翻倍。

对于纯英文代码库，small够用了。

和其他方案的对比

市面上解决"大代码库上下文"问题的方案不少，简单对比一下：

Aider的repo-map： 用tree-sitter解析代码结构，生成函数/类的索引。优点是不需要外部服务，缺点是只能按符号名搜索，做不到语义搜索。你问"处理用户登录的代码在哪"，repo-map找不到，claude-context可以。

Cursor的内置索引： Cursor有自己的代码索引，但只在Cursor内部用。如果你同时用Claude Code和Cursor（很多人都这样），Cursor的索引帮不了Claude Code。claude-context的索引是通用的，所有MCP兼容工具都能用。

直接用@codebase： Cursor的@codebase会把整个代码库内容灌进上下文。几百行的项目没问题，几万行直接炸Token限制。claude-context只检索相关片段，不会把整个代码库扔进去。

什么时候该用，什么时候不该用

该用的情况： - 代码量超过10万行 - 经常需要跨模块修改代码 - 多人协作的项目，你不熟悉所有模块 - Token费用已经成为痛点

不用的情况： - 个人小项目，几千行代码 - 你对代码库了如指掌，能直接告诉Agent去看哪个文件 - 不想依赖外部云服务（Zilliz Cloud）

有一点要注意：claude-context会把你的代码做成Embedding存到Zilliz Cloud。虽然Embedding不能反向还原出源代码，但如果你的项目有严格的代码安全合规要求，需要评估一下这个风险。Zilliz也提供私有部署的Milvus方案，但配置复杂度会高不少。

总结

claude-context解决了一个很实际的问题：大型代码库下AI编程工具的上下文效率。配置过程不复杂，Claude Code一条命令就能搞定，其他工具也就是改一个JSON配置文件的事。

实际效果取决于项目规模。10万行以上的项目，Token节省在70%左右，搜索准确率提升明显。小项目收益不大，不用专门折腾。

项目地址：github.com/zilliztech/claude-context

如果你在用Claude Code或者Cursor做大项目的开发，建议花5分钟配一下试试。