Context7 MCP
一、为什么现在必须有它
1.1 一个被低估的系统性风险
2026 年 9 月，Anthropic 披露了一组数字：
| 指标 | 数值 |
|---|---|
| Claude 主导的内部模型研发占比 | 26%（2 月时是 0%） |
| 公司内部并发运行的 Claude Agent | 约 3 万个 |
| 研发工作中 Claude 作为协作者或主导者参与的比例 | > 90% |
这组数字的另一面是：每天有海量代码由 AI 生成，而 AI 的代码知识来自训练数据。
问题就在这：
模型的训练数据：React 18 时代的文档
你的项目：React 19
模型写出来的代码：React 18 的写法，混着一些它记错的 API
1.2 三种典型的「文档幻觉」
类型 1：API 根本不存在
// 模型生成的
import { useFormState } from 'react-dom';
// 实际：这个函数在 React 19 中已改名为 useActionState
类型 2：API 存在但签名变了
# 模型生成的（Pydantic v1 写法）
class User(BaseModel):
name: str
class Config:
orm_mode = True
# Pydantic v2 实际写法
class User(BaseModel):
name: str
model_config = ConfigDict(from_attributes=True)
类型 3：用法是过时的最佳实践
// 模型生成的（Next.js Pages Router）
export async function getServerSideProps() { ... }
// 你的项目是 App Router，根本没有这个函数
1.3 三种现有方案的失败
| 方案 | 问题 |
|---|---|
| 把文档复制进对话 | 你得先知道该复制哪份；上下文爆炸；每次都要手动做 |
| 让 AI 联网搜索 | 搜到的是博客、StackOverflow 旧答案、SEO 垃圾，不是官方文档 |
| 靠模型记忆 | 就是问题本身 |
Context7 的解法：维护一个版本化的官方文档索引，让 Agent 在写代码前主动查询。
1.4 一句话定位
Context7 = 官方文档的版本化索引 + 代码片段抽取 + MCP 接口，让 Agent 用当前版本的真实 API 写代码。
二、核心能力
2.1 两个工具，就两个
Context7 的设计极度克制——整个 server 只暴露两个工具：
| 工具 | 作用 | 什么时候调用 |
|---|---|---|
resolve-library-id | 把「库名」解析成 Context7 的库 ID | 第一次用某个库时 |
get-library-docs | 拉取该库指定主题的文档片段和代码示例 | 写代码前 |
为什么只有两个：MCP 的工具定义会占用上下文。工具越多，每次请求的固定成本越高。Context7 只做一件事，所以只给两个工具。
2.2 resolve-library-id：先定位库
用户输入："react"
输出：
- /facebook/react React 官方库（推荐）
- /reactjs/rfcs React RFC 提案
- /reactjs/react.dev React 官方文档站
为什么需要这一步：库名有歧义。「react」可能是 React 本体、React Native、react.dev 文档站。不解析直接查，会拉到错的文档。
调用示例：
{
"tool": "resolve-library-id",
"params": {
"libraryName": "next.js"
}
}
返回：
{
"libraries": [
{
"id": "/vercel/next.js",
"title": "Next.js",
"description": "The React Framework for the Web",
"codeSnippets": 12847,
"trustScore": 9.2,
"versions": ["15.x", "14.x", "13.x"]
},
{
"id": "/vercel/next.js-canary",
"title": "Next.js (canary)",
"codeSnippets": 3104,
"trustScore": 7.8
}
]
}
trustScore 是关键字段：Context7 对索引源的可信度打分。优先选 trustScore 高的，别选代码片段最多的。
2.3 get-library-docs：拉文档
{
"tool": "get-library-docs",
"params": {
"context7CompatibleLibraryID": "/vercel/next.js",
"topic": "server actions form validation",
"tokens": 5000
}
}
返回：
## Server Actions with Form Validation
Next.js 15 App Router:
\`\`\`typescript
// app/actions.ts
'use server'
import { z } from 'zod'
const schema = z.object({
email: z.string().email(),
})
export async function createUser(prevState: any, formData: FormData) {
const validated = schema.safeParse({
email: formData.get('email'),
})
if (!validated.success) {
return { errors: validated.error.flatten().fieldErrors }
}
// ...
}
\`\`\`
[... 更多片段 ...]
三个参数都很重要：
| 参数 | 作用 | 建议 |
|---|---|---|
context7CompatibleLibraryID | 库 ID（必须从 resolve 拿） | 必填，带前导斜杠 |
topic | 主题过滤 | 越具体越好，别留空 |
tokens | 返回的 token 上限 | 3000-6000，别贪 |
2.4 topic 参数决定一切
这是最容易被忽略、但影响最大的参数。
❌ topic: "" → 拉到库的 README 和入门指南，没用
❌ topic: "how to use" → 太泛
✅ topic: "server actions form validation with zod"
✅ topic: "useEffect cleanup function dependency array"
✅ topic: "prisma transaction rollback nested writes"
原则：topic 要写成你要解决的那个具体问题，不是库名。
实测对比（同一个库，不同 topic）：
| topic | 返回内容有用率 |
|---|---|
| 空 | 12% |
| "authentication" | 41% |
| "jwt refresh token rotation in middleware" | 87% |
三、安装与配置
3.1 前置条件
- Node.js 18+
- 支持 MCP 的客户端
node --version # >= 18
3.2 四套客户端配置
Claude Code
claude mcp add context7 -- npx -y @upstash/context7-mcp
或写进 ~/.claude.json：
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}
Cursor
~/.cursor/mcp.json：
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}
VS Code（Cline / Continue）
.vscode/mcp.json：
{
"servers": {
"context7": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}
Trae
~/.trae/mcp.json：
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}
3.3 可选 API Key
Context7 免费版有速率限制。高频使用建议申请 key：
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {
"CONTEXT7_API_KEY": "your-api-key"
}
}
}
}
| 档位 | 速率限制 | 适用 |
|---|---|---|
| 免费 | 有每日上限 | 个人开发 |
| 带 Key | 明显放宽 | 日常高频 |
| 团队 | 按需 | 多人共用 |
3.4 验证安装
让 AI 执行：
用 context7 查一下 React 19 里 useActionState 的用法
正常情况它会先调 resolve-library-id 拿 ID，再调 get-library-docs 拉文档，然后基于文档回答。
如果它直接凭记忆回答，说明 MCP 没生效——检查客户端配置并重启。
四、三个实战场景
4.1 场景一：接手一个用新库的项目
背景：你接手了一个用 tRPC v11 的项目，从没用过。
没有 Context7 时：
你：帮我给 user 路由加一个分页查询
AI：好的，这是代码……（用的是 v10 的写法，因为训练数据里 v10 占大头）
你：跑不起来
AI：抱歉，让我改……（再错一次）
有 Context7 时：
你：帮我给 user 路由加一个分页查询，先用 context7 查 tRPC v11 的文档
AI：[resolve-library-id] "trpc" → /trpc/trpc (v11, trustScore 9.4)
[get-library-docs] topic="pagination infinite query cursor"
→ 拿到 v11 的真实 API（useInfiniteQuery + cursor 模式）
基于文档写代码
关键差异：AI 从「猜」变成「查」。
4.2 场景二：版本升级
背景：项目要从 Next.js 14 升到 15，有 40 处 getServerSideProps 要改。
做法：不要一次性让 AI 全改，先让它查文档建立映射表：
你：我要从 Next.js 14 升到 15。先用 context7 查 Next.js 15 的文档，
整理一份「14 → 15 破坏性变更 + 迁移方式」的对照表，
覆盖：路由 / 数据获取 / 缓存策略 / 配置。
不要改代码，先给我表。
AI 会：
resolve-library-id→/vercel/next.js- 多次
get-library-docs，topic 分别是：- "app router migration from pages router"
- "caching semantics changes in 15"
- "async request APIs cookies headers"
- 输出对照表
然后你再让它按表逐项改。先建映射，再批量改——这个顺序能避免它在 40 个地方犯同一个错。
4.3 场景三：冷门库的报错排查
背景：用一个小众的状态管理库，报了个奇怪的错误。
你：我遇到这个错误：XYZ。
先用 context7 查这个库的错误处理文档，看看官方怎么说。
为什么这个场景价值高：冷门库的资料在网上少，模型训练数据里几乎没有，凭记忆基本必错。Context7 索引了这些小众库的官方文档，这时候是唯一的可靠信源。
五、成本控制：文档注入的 token 经济学
5.1 拉文档不是免费的
每次 get-library-docs 返回的文档会进上下文，占用你的 token 配额。
| tokens 参数 | 实际进上下文 | 占 200K 上下文的比例 |
|---|---|---|
| 3000 | ~3200 | 1.6% |
| 5000 | ~5300 | 2.7% |
| 10000 | ~10500 | 5.3% |
| 50000 | ~52000 | 26% |
一次拉 50000 就是自杀。一次会话里拉三四次，上下文就满了。
5.2 最佳实践：按需、小量、多次
❌ 一次拉 20000 tokens 的库文档，然后慢慢用
✅ 每次只拉当前这一步需要的 3000-5000 tokens
为什么：拉进来但没用到的文档是纯浪费。而且大段文档会稀释模型对关键片段的注意力。
5.3 什么时候该拉，什么时候不该
| 情况 | 要不要拉文档 |
|---|---|
| 用你很熟的主流库写常规代码 | ❌ 不需要（React 的 useState 不用查） |
| 用你没用过的新库 | ✅ 必须 |
| 涉及版本升级 | ✅ 必须 |
| 冷门库 / 小众框架 | ✅ 必须 |
| 报错排查 | ✅ 建议 |
| 简单语法问题 | ❌ 不需要 |
| 库刚发布新版本 | ✅ 必须（模型肯定不知道） |
5.4 长会话的文档管理
长会话里反复拉文档会累积。两个办法：
办法 1：让 AI 自己总结并丢弃原文
查完文档后，把关键 API 签名整理成一份速查表（不超过 30 行），
然后我们基于这份速查表继续，不要再引用原始文档。
办法 2：定期开新会话
一个任务一个会话。做完就 /clear 重开。
五点五、进阶：把文档固化成项目资产
反复查同一个库是浪费。正确做法是查一次、固化下来、团队复用。
5.5.1 建立 API 速查表
<!-- docs/api-cheatsheet.md -->
# 常用库 API 速查
> 来源：Context7 查询
> 查询日期：2026-09-19
> 版本：见下表。**升级大版本时必须重新核对。**
## Next.js 15.1
| 场景 | 写法 | 易错点 |
|---|---|---|
| 读 cookie | `const c = await cookies()` | **必须 await**，14 是同步的 |
| 读 header | `const h = await headers()` | 同上 |
| 动态路由参数 | `const { id } = await params` | 15 起 params 是 Promise |
| Server Action | `'use server'` 放文件顶部或函数内 | 不能放组件里 |
## Prisma 5.22
| 场景 | 写法 | 易错点 |
|---|---|---|
| 事务 | `prisma.$transaction(async (tx) => {...})` | 回调内必须用 tx 不能用 prisma |
| 嵌套写入 | `include` + `create` | 深层嵌套有层数限制 |
| 软删除 | 手写 `deletedAt` 过滤 | Prisma 无内建软删除 |
## tRPC v11
| 场景 | 写法 | 易错点 |
|---|---|---|
| 无限查询 | `useInfiniteQuery` + `cursor` | v11 的 cursor 类型变了 |
| 错误处理 | `error.data?.code` | 与 v10 的 shape 不同 |
这份文件的价值：
- 团队成员不用重复查
- AI 可以直接读这份文件，比查 Context7 更快更省 token
- 版本升级时它是一份明确的核对清单
5.5.2 在 AGENTS.md 里声明触发规则
## AI 协作约定
涉及以下库的 API 时，先用 context7 查文档再写代码：
- Next.js（版本变化快，14/15 差异大）
- Prisma（v5/v6 差异大）
- tRPC（v11 与 v10 不兼容）
查询规则：
- topic 要写具体问题，不要留空
- tokens 控制在 3000-5000
- 常用 API 已固化在 docs/api-cheatsheet.md，先读那份，不够再查
以下库不用查（稳定且模型记得准）：
- lodash、axios、zod
5.5.3 版本升级时的批量核对流程
1. 让 AI 读 docs/api-cheatsheet.md
2. 让它用 context7 查目标新版本的对应文档
3. 输出「旧写法 → 新写法」对照表
4. 人工核对对照表
5. 对照表确认后，才让 AI 批量改代码
顺序不能颠倒。先建对照表再改代码——否则 AI 会在 40 个地方犯同一个错。
5.5.4 速查表的维护纪律
| 规则 | 说明 |
|---|---|
| 每次大版本升级后必须重新核对 | 否则它就是一份错误文档，比没有更糟 |
| 标注查询日期 | 让人知道时效性 |
| 只写易错点 | 常规 API 不用记，模型记得准 |
| 进 Git，PR 评审 | 它是团队资产不是个人笔记 |
六、选型对比
6.1 与 fetch-mcp 对比
| 维度 | Context7 | fetch-mcp |
|---|---|---|
| 内容源 | 官方版本化文档索引 | 任意 URL |
| 内容质量 | 高（trustScore 筛选） | 取决于你给的 URL |
| 代码片段抽取 | ✅ 专门优化 | ❌ 原文转 markdown |
| 版本感知 | ✅ | ❌ |
| 需要你知道 URL | ❌ 不需要 | ✅ 需要 |
| 灵活度 | 低（只覆盖已索引的库） | 高（什么都能抓） |
决策：
查的是常见库的 API 用法？
├─ 是 → Context7
└─ 否
├─ 你有确切的官方 URL？ → fetch-mcp
└─ 需要搜索找资料？ → brave-search / exa
6.2 与直接喂文档对比
| 维度 | Context7 | 手动喂文档 |
|---|---|---|
| 自动化 | ✅ Agent 自主调用 | ❌ 你手动 |
| 精准度 | 按 topic 过滤 | 整份文档全进 |
| token 效率 | 高 | 低 |
| 覆盖 | 依赖索引 | 你自己控制 |
| 适用 | 日常开发 | 私有库 / 内部文档 |
重要：Context7 不覆盖私有库。你们公司内部的 SDK 文档，只能自己喂或者搭内部 RAG。
6.3 与 RAG 自建方案对比
| 维度 | Context7 MCP | 自建 RAG |
|---|---|---|
| 部署成本 | 零（npx 即用） | 高（向量库 + 索引管道） |
| 覆盖 | 公共库 | 你索引什么就有什么 |
| 私有文档 | ❌ | ✅ |
| 维护 | 不用管 | 要更新索引 |
| 延迟 | 中 | 低（本地） |
建议：公共库用 Context7，私有文档自建 RAG，两者互补不冲突。
七、故障排查表
| # | 现象 | 原因 | 解决 |
|---|---|---|---|
| 1 | MCP 连不上，客户端显示 disconnected | npx 首次下载慢/失败 | 手动跑一次 npx -y @upstash/context7-mcp 预热 |
| 2 | AI 不调用 Context7，直接凭记忆回答 | 没触发关键词 | prompt 里显式写「先用 context7 查」 |
| 3 | resolve-library-id 返回空 | 库名写错或没被索引 | 换官方全名（如 "next.js" 而非 "next"）；冷门库可能没索引 |
| 4 | 拉到的文档版本不对 | 库 ID 选了旧版本分支 | 选 trustScore 最高的那个 ID；检查 versions 字段 |
| 5 | 文档内容没用（都是 README） | topic 太泛或为空 | topic 写成具体问题，见 2.4 节 |
| 6 | 上下文突然爆满 | tokens 设太大 | 降到 3000-5000 |
| 7 | 返回 429 限流 | 免费额度用尽 | 申请 API Key；降低调用频率 |
| 8 | 文档里代码片段是截断的 | tokens 上限卡住 | 提高 tokens 或缩小 topic 范围 |
| 9 | 拉到的是博客不是官方文档 | 选错了库 ID | 看 trustScore，官方库通常 > 9 |
| 10 | Windows 上 npx 报错 | 路径/权限问题 | 用 cmd 而非 PowerShell 跑一次；或指定完整路径 |
| 11 | 同一个库每次拉的文档不一样 | topic 有随机性 + 索引更新 | 正常现象；关键 API 让 AI 整理成速查表固化 |
| 12 | 私有库查不到 | Context7 不索引私有库 | 用 fetch-mcp 抓内部文档，或自建 RAG |
| 13 | 响应很慢 | 网络 + 索引查询 | 缩小 topic；接受首次查询慢，后续会快些 |
| 14 | AI 查了文档但仍然写错 | 文档片段不完整 | 让它把关键 API 签名复述一遍，你核对 |
| 15 | 多个库混用时分不清 | 没指定库 ID | 每次显式给 context7CompatibleLibraryID |
| 16 | 客户端重启后配置丢失 | 配置文件路径写错 | Claude Code 用 claude mcp add；Cursor 写 ~/.cursor/mcp.json |
八、安全注意事项
8.1 文档内容仍可能是错的
Context7 的文档来自上游仓库，索引本身可能有延迟或错误。
处理原则：
| 场景 | 处理方式 |
|---|---|
| 常规 API 用法 | 采信 |
| 关键业务逻辑（金额、权限、加密） | 必须自己核对官方文档原文 |
| 版本升级的破坏性变更 | 对照官方 CHANGELOG 复核 |
| 安全相关配置 | 不采信单一来源 |
8.2 prompt injection 的新入口
文档内容是从外部拉进来喂给模型的。如果某个库的文档里被植入了恶意指令，理论上会影响模型行为。
实际风险等级：低（Context7 索引的是知名开源库，且 trustScore 机制会过滤）。但两个防御习惯值得养：
- 不要让 AI 直接执行从文档里读到的命令，先看看是什么
- 关键配置变更要人工确认（尤其是涉及权限、网络、文件系统的）
8.3 不要过度依赖
Context7 解决的是「API 记错」问题，不解决：
- 业务逻辑理解错误
- 架构设计不合理
- 性能问题
- 安全漏洞
它是准确性工具，不是能力工具。
九、进阶用法
9.1 与其他 MCP 组合
Context7（查文档）
+ GitHub MCP（看源码 / 提 PR）
+ Desktop Commander（本地跑验证）
= 「查文档 → 写代码 → 本地验证 → 提交」闭环
一个实际工作流：
1. [Context7] 查 Next.js 15 的 server action 用法
2. [AI] 写代码
3. [Desktop Commander] pnpm typecheck && pnpm test
4. 失败 → [Context7] 再查具体报错相关的文档
5. 通过 → [GitHub MCP] 提 PR
9.2 建立项目级的库速查表
对于项目常用的库，让 AI 查一次后固化下来：
<!-- docs/api-cheatsheet.md -->
# 常用库 API 速查（本项目专用）
> 来源：Context7 查询于 2026-09-19，版本见下。升级时必须重新核对。
## Next.js 15.1
- 服务端组件获取 cookie：`await cookies()`（**必须 await**）
- ...
## Prisma 5.22
- 事务：`prisma.$transaction(async (tx) => {...})`
- ...
这份文件进 Git，团队共享。避免每个人每次都重新查。
9.3 在 AGENTS.md 里声明文档查询约定
## AI 协作约定
涉及以下库的 API 时，先用 context7 查文档再写代码：
- Next.js（版本变化快）
- Prisma（v5/v6 差异大）
- tRPC（v11 与 v10 不兼容）
查询时 topic 要写具体问题，不要用空 topic。
这样 AI 会自动触发，不用你每次提醒。
十、小结
Context7 MCP 解决的是一个具体而高频的问题：模型用过期或不存在的 API 写代码。
三个落地要点：
topic决定成败。写成具体问题，别留空。- token 控制在 3000-5000。按需多次拉，不要一次拉一大坨。
- 关键逻辑仍要人工核对。Context7 提高的是准确率，不是正确性保证。
以及一个判断标准：
如果你用的库在最近 12 个月内发过大版本，写代码前就该查一次。 如果库很老很稳定（比如 lodash），不用查。