# Context7

Canonical: https://cqbase.net/zh/entry/context7
Chinese: https://cqbase.net/zh/entry/context7
English: https://cqbase.net/en/entry/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](https://context7.com) 即可。REST API 见官方 [API Guide](https://context7.com/docs/api-guide)。

## 怎么装

核验日期为 2026-11-15（Asia/Shanghai），命令均来自官方文档。请先到 [Context7 控制台](https://context7.com/dashboard?tab=settings) 申请免费 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`。远程示例：

```json
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

本地用 `npx` 运行 `@upstash/context7-mcp` 并传入 `--api-key`。改完后重启。完整 JSON 见 [Cursor 文档](https://context7.com/docs/clients/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](https://context7.com/docs/resources/troubleshooting) 与 [API Guide](https://context7.com/docs/api-guide#rate-limits)。
- 401 Unauthorized：确认密钥有效且以 `ctx7sk` 开头。远程用 `Authorization: Bearer …`，本地 stdio 用 `--api-key`。插件不读取 `CONTEXT7_API_KEY`。[issue #716](https://github.com/upstash/context7/issues/716) 曾报告即使用新 key 也会出现该错误；issue 已于 2025-12-12 关闭，应先检查请求头格式。
- 本地 npx 出现 `ERR_MODULE_NOT_FOUND` 或连不上：可改用 `@upstash/context7-mcp@latest`、`bunx` / `deno`，或改连远程 URL。[issue #12](https://github.com/upstash/context7/issues/12) 加上 `@latest` 后即可启动。Windows 上本地 npx 若让 MCP 失效，[issue #829](https://github.com/upstash/context7/issues/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](https://context7.com/docs/resources/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](https://github.com/upstash/context7) 使用 MIT 许可，产品站点是 [context7.com](https://context7.com)。本文依据 2026-11-15 查阅的 README 与官方 [CLI](https://context7.com/docs/clients/cli)、[Claude Code](https://context7.com/docs/clients/claude-code)、[Cursor](https://context7.com/docs/clients/cursor)、[排障](https://context7.com/docs/resources/troubleshooting)、[定价](https://context7.com/docs/plans-pricing) 和 [API](https://context7.com/docs/api-guide) 文档，用自己的话写成，供 CQBase 上下文库审阅。若随后有改动，以官网为准。

## 收录信息

- 作者: upstash
- 许可证: MIT
- 来源: https://github.com/upstash/context7
- 收录: 2026-11-15
- GitHub 星标: 64830（采集 2026-11-15）

