cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

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 的当前说明。提示词来自官方文档。本次没有在本机实际跑这一问,因此不编造返回的文档或生成代码。

  1. 完成安装后,确认客户端能看到 Context7(Claude Code 用 /mcp 或 claude mcp list,Cursor 看 Tools & MCP)。
  2. 在新对话中发送: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。
  3. 按官方对两个工具的说明:提示词里若已有 /vercel/next.js 这类 ID,代理应直接调用 query-docs。若只给了库名,应先调用 resolve-library-id,再用返回的 ID 取文档。若已用 npx ctx7 setup 安装技能,问到库相关问题时可以自动触发,不一定要写出 “use context7”。
  4. 文档返回后,请自行确认取到的是 App Router 或你要的 Next.js 16 说明,而不是同名的其他库或未使用的版本。官方建议在提示词里写明版本。
  5. 不要把这一次回答当成永久正确。重要改动仍应对照项目里的依赖版本和上游文档。

常见坑

下列问题都能在官方排障页或公开 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 上下文库审阅。若随后有改动,以官网为准。

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。