MCP
Context7
给代理拉取当前文档的 MCP,减少它拿过时 API 编代码。
Upstash 的 Context7 把库的文档提供给编码代理,仓库是 MIT,产品站在 context7.com。它要解决的问题很具体:代理记得的是训练时的旧接口,文档已经改了。
把它接到支持 MCP 的客户端之后,在提问里点名库名,让代理先取文档再写代码。仍然要看它取回的是不是你锁定的版本。
本页是导读,不是原文。
解决什么问题
编码代理记住的接口,常常停在训练时的样子。库已经改版,它仍可能写出不存在的函数,或把旧教程当成当前做法。Context7 做的事很具体:在你提问时,从索引里取出相关说明和示例,交给代理去读。
官方提供两种用法。MCP 模式会加入 resolve-library-id 和 query-docs,由代理直接调用;另一种是安装技能,让代理用 ctx7 命令行查询,不必走 MCP。本文以接到 Claude Code 或 Cursor 的 MCP 为主。
索引里的库由社区提交。README 写明不保证每份文档都准确或完整。取回内容后,仍应对照你项目里锁定的版本。
适合谁
适合在 Claude Code、Cursor 或其他 MCP 客户端里查询当前库用法,或要在提示词里钉死库 ID、版本的人。若只在浏览器里翻文档,打开 context7.com 即可。REST API 见官方 API Guide。
怎么装
核验日期为 2026-11-15(Asia/Shanghai),命令均来自官方文档。请先到 Context7 控制台 申请免费 API key(官方建议用来提高限额)。密钥以 ctx7sk 开头,只显示一次,不要写入仓库。
ctx7 命令行需要 Node.js 22.13 或更新版本;本地跑 MCP 包时,排障文档要求 v20.18.1 或更高。不想处理本机 Node,可改连 https://mcp.context7.com/mcp。
一条命令
在终端运行 npx ctx7 setup。按提示用 OAuth 登录、生成 key,并选择 MCP 或「CLI + 技能」。只装给一个客户端时,可用 --claude 或 --cursor。登录是设备码流程,本机或 SSH 都可以完成。要撤掉这次配置,运行 npx ctx7 remove。
Claude Code
除 setup 外,可用官方插件连接托管 MCP,无需本机 Node.js。执行 /plugin marketplace add upstash/context7,再执行 /plugin install context7@context7-marketplace。然后重启,运行 /mcp,选中 Context7 并按浏览器登录。官方写明插件不必填写 key,也不读取 CONTEXT7_API_KEY。无界面、SSH 或 CI 若必须用 key,请改走 npx ctx7 setup --claude 或下面的手动命令。
远程:claude mcp add --scope user --header "Authorization: Bearer YOUR_API_KEY" --transport http context7 https://mcp.context7.com/mcp
本地:claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY
--scope user 为用户级配置,去掉则只作用于当前项目。可用 claude mcp list 检查。
Cursor
快捷方式是 npx ctx7 setup --cursor。手动配置时,官方推荐改 ~/.cursor/mcp.json,或在项目中放 .cursor/mcp.json。远程示例:
{
"mcpServers": {
"context7": {
"url": "https://mcp.context7.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}本地用 npx 运行 @upstash/context7-mcp 并传入 --api-key。改完后重启。完整 JSON 见 Cursor 文档。
Cursor Cloud Agents 不读取本机或仓库里的 mcp.json,须在其界面添加同一地址的 HTTP 服务器,请求头用官方核实过的 Context7-API-Key(带下划线的名字可能被代理丢掉)。远程 HTTP 也可用 https://mcp.context7.com/mcp/oauth;OAuth 仅用于远程,本地 stdio 仍要 API key。
免费额度
没有 key 时,官方只写「限额较低」,未公布次数。有免费账号和 key 时,每月合计 1,000 次调用(MCP、CLI 与 API);用完后暂停到下月,其间每天另有 20 次奖励额度。查找或取文档各计一次。用量可在控制台或 GET /api/v2/usage 查看(该请求不计次)。
一个实际例子
目的是让已接好 Context7 的代理去查 Next.js App Router 的当前说明。提示词来自官方文档。本次没有在本机实际跑这一问,因此不编造返回的文档或生成代码。
- 完成安装后,确认客户端能看到 Context7(Claude Code 用
/mcp或claude mcp list,Cursor 看 Tools & MCP)。 - 在新对话中发送:
use context7 with /vercel/next.js for app router setup。若还不知道库 ID,可用:use context7 to show me how to set up a proxy in Next.js 16。 - 按官方对两个工具的说明:提示词里若已有
/vercel/next.js这类 ID,代理应直接调用query-docs。若只给了库名,应先调用resolve-library-id,再用返回的 ID 取文档。若已用npx ctx7 setup安装技能,问到库相关问题时可以自动触发,不一定要写出 “use context7”。 - 文档返回后,请自行确认取到的是 App Router 或你要的 Next.js 16 说明,而不是同名的其他库或未使用的版本。官方建议在提示词里写明版本。
- 不要把这一次回答当成永久正确。重要改动仍应对照项目里的依赖版本和上游文档。
常见坑
下列问题都能在官方排障页或公开 issue 中找到。
- 限额或 429:没有 key,或免费额度用完,都可能被限速。官方建议把 key 写入配置;超额响应会带
Retry-After等头。见 Troubleshooting 与 API Guide。 - 401 Unauthorized:确认密钥有效且以
ctx7sk开头。远程用Authorization: Bearer …,本地 stdio 用--api-key。插件不读取CONTEXT7_API_KEY。issue #716 曾报告即使用新 key 也会出现该错误;issue 已于 2025-12-12 关闭,应先检查请求头格式。 - 本地 npx 出现
ERR_MODULE_NOT_FOUND或连不上:可改用@upstash/context7-mcp@latest、bunx/deno,或改连远程 URL。issue #12 加上@latest后即可启动。Windows 上本地 npx 若让 MCP 失效,issue #829 改回远程地址后恢复。排障页也为超时提供了cmd /c npx或写死 Node 路径的示例。 - 404 找不到库:ID 应为
/owner/repo或带版本的/owner/repo/version。可先用resolve-library-id搜索,或到 context7.com 确认该库是否存在。 - 改完 Cursor 配置却没有工具:需 Cursor 1.0 或更新版本,并重启;Cloud Agent 还要在当次运行前启用服务器。
- 取到了文档却仍像旧 API:可能解析到了同名库或错误版本。把库 ID 和版本写进提示词,并人工查看返回内容。
更完整的清单见 Troubleshooting。可用 curl https://mcp.context7.com/ping 检查远程服务是否返回含 pong 的 JSON。
FAQ
一定要有 API key 吗?
不一定。未登录也能用 MCP 和多数查询命令,但官方推荐用 key 提高限额。Claude Code 插件用浏览器登录,不必填写 key。有账号和 key 的免费套餐是每月 1,000 次。
一定要写 “use context7” 吗?
不是必须。若已用 ctx7 setup 安装技能,问到库或 API 时可以自动触发;也可以显式写上,或把官方规则写入 Cursor 或 CLAUDE.md。
两个 MCP 工具做什么?
resolve-library-id 用库名和任务找出库 ID(如 /vercel/next.js)。query-docs 用该 ID 和具体问题取文档,可选的 language 用来提高某种语言示例的排序。命令行对应 ctx7 library 和 ctx7 docs。
可以指定版本吗?
可以。官方示例会写 “Next.js 16”,或使用 /vercel/next.js/v16.2.9。若该版本尚未索引,仍可能返回最接近的已索引版本,并在响应里标明。
文档一定正确吗?
不一定。README 写明内容由社区贡献,不保证准确或完整。请把取回的内容当作当前索引的摘录,并对照你的依赖版本和上游文档。
来源与许可
仓库 upstash/context7 使用 MIT 许可,产品站点是 context7.com。本文依据 2026-11-15 查阅的 README 与官方 CLI、Claude Code、Cursor、排障、定价 和 API 文档,用自己的话写成,供 CQBase 上下文库审阅。若随后有改动,以官网为准。