upstash/context7 · 上手攻略

仓库：upstash/context7
链接：https://github.com/upstash/context7
分类：skill
作者：spark
更新：2026-07-13

是什么

Context7 是由 Upstash 团队（推 Redis / Vector / QStash 的那家）开源并维护的「MCP 文档服务」。它把 GitHub 上常见开源库的 README、官方文档、版本说明抓取、解析、切片成一个可被 LLM 检索的索引，然后通过 Model Context Protocol（MCP）暴露给 Cursor、Claude Code、OpenCode、Codex、Cline、Windsurf、Continue 等 AI 编程客户端。

它解决的就是「AI 写代码时拿着过时的训练数据瞎编 API」这个老问题：在没有 Context7 的情况下，模型会基于 1–2 年前的快照帮你写代码，写出来可能是 Next.js 13 的写法、Supabase v1 的 API、React 18 的 hook；用了 Context7 之后，模型能在每次生成前去问「这个库 v3.2 的官方文档怎么说」，再基于真实当前文档写代码。

仓库本身是「MCP 服务器的源码」，配套还有 CLI（ctx7）、TypeScript SDK、CLI + Skills 模式，以及一个 280+ 翻译的官方文档站（context7.com）。

解决什么问题

具体痛点对应 README 里列的三类失败模式：

Code examples are outdated — 模型用 1 年前的 API 写代码，跑不起来。
Hallucinated APIs that don't even exist — 模型臆造根本不存在的函数。
Generic answers for old package versions — 回答过于通用，没考虑项目实际版本。

Context7 给出的是「版本对齐 + 源码对齐」的文档片段（doc-snippets），配合一个简洁的协议让 agent 在工具调用中拿到正确代码。

快速安装

Context7 提供两种主流接入方式，README 推荐用 CLI 一键安装（需要 Node.js 18+）：

# 一键安装（推荐）：会做 OAuth、生成 API key、自动写好 skill
npx ctx7 setup

# 指定 agent
npx ctx7 setup --claude
npx ctx7 setup --cursor
npx ctx7 setup --opencode

如果想手动配（例如在 CI 容器里、不想跑交互式 OAuth），可以直接用远程 MCP 端点 https://mcp.context7.com/mcp，把 API key 放在 CONTEXT7_API_KEY 这个 header 里。

Claude Code（手动）：

claude mcp add --scope user --header "CONTEXT7_API_KEY: YOUR_API_KEY" \
  --transport http context7 https://mcp.context7.com/mcp

Cursor（写在 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "YOUR_API_KEY" }
    }
  }
}

VS Code（.vscode/mcp.json，需要装扩展 Upstash.context7-mcp）：

{
  "servers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "YOUR_API_KEY" }
    }
  }
}

跑完安装以后，建议在项目里建一条规则，让 agent 自动用 Context7 而不是每次手动加 use context7：

# CLAUDE.md / Cursor Rules
Always use Context7 when I need library/API documentation,
code generation, setup or configuration steps without me having
to explicitly ask.

想彻底卸载：

npx ctx7 remove
# 加上全局装的：
npm uninstall -g ctx7

核心用法

工作流其实是「prompt 里加一句 use context7（或者 Library ID）」 → agent 调用 MCP 工具 → 拿到匹配版本的文档片段。

最小例子（直接复制给 agent）：

Create a Next.js middleware that checks for a valid JWT in cookies
and redirects unaauthenticated users to /login. use context7

指定库 + 指定版本（更精准，跳过匹配步骤）：

Implement basic authentication with Supabase. use library
/supabase/supabase for API and docs.

How do I set up Next.js 14 middleware? use context7

手动调 CLI 调试（不是必须的，但能让你看到底层返回什么）：

# 安装
npm i -g ctx7
# 搜库
ctx7 library supabase "auth email password sign up"
# 拉文档
ctx7 docs /supabase/supabase "how to do email/password sign up"

MCP 服务器侧暴露的两个 tool（给做 agent 的人看的）：

resolve-library-id — 输入 libraryName + query，返回 Context7 Library ID（如 /vercel/next.js）。
query-docs — 输入 libraryId + query，返回匹配版本的文档片段。

注：上面这一节里 npx ctx7 setup 是 README 当前推荐入口；如果你只想跑本地 MCP 服务器而不是用云端（mcp.context7.com），也可以 npx -y @upstash/context7-mcp --api-key YOUR_API_KEY 走 stdio，Cursor 客户端把它当 type=local 来配。具体格式以 https://context7.com/docs/resources/all-clients 为准 —— README 上写「30+ client」覆盖列表在那里。

典型适用场景

AI 写新代码：让 Cursor / Claude Code 写新项目脚手架时直接拿对的版本。
跨版本升级：把项目从 Next.js 13 升到 15，把 React 17 升到 19 时，让 agent 拿到目标版本的新 API 而不是旧记忆。
接入冷门库：本机训练数据稀薄的库（一般小众但用户量增长的 SDK），用 use library /org/repo 直接拽源码里的文档。
MCP 协议实践：要做自定义 agent / 工具链时，可以把它当成一个标准 MCP server 参考实现 + SDK 来源。

不太适合的场景：

要「训练知识」型问答（Context7 拉的是公开文档，不会做总结式回答）。
私有 / 内部库的文档（要先把库提交到 Context7 索引，参考 https://context7.com/docs/adding-libraries，审核通过才能被检索）。

坑与注意

API key 推荐要有：README 明说没 key 也能用但有限速，频繁开发体验明显劣化。先去 https://context7.com/dashboard 拿一个免费 key。
CLI 第一次运行会开浏览器做 OAuth — 在无 GUI 的远端服务器上跑 npx ctx7 setup 不会成功，请用上面的手动 MCP 配置。
Library ID 不是 1:1 仓库名：要写 /owner/repo 形式（如 /vercel/next.js、/mongodb/docs），写错会回退到模糊匹配，浪费 token。
响应是「文档片段」不是「AI 回答」：你不会拿到一段人话总结，拿到的是切好的 markdown 文本，再交给主模型去合成。这对调试很有用 —— 想看 Context7 实际拽了什么，直接看 agent 的 tool call 输出。
隐私 / 合规：Context7 拉的是公开仓库文档；如果是 fork 内部代码、私有依赖，不会被收录。
准确度非 100%：README 自带 Disclaimer 写明文档是「社区贡献」，Upstash 不为每个库担保准确性 —— 关键业务代码还是要人工 review。
Node 版本：CLI 需要 Node.js 18+（README 原文）。

与同类对比

Refly / Dify 内置知识库 —— 偏企业内部知识 / RAG，需要自己上传和切片；Context7 是「公共库的版本对齐」专才。
DeepWiki / DevDocs / Dash —— DevDocs 是给人看的本地 docset；DeepWiki（Devin 那家）做的是仓库级 AI 解释；Context7 专注「让 LLM 在工具调用时拿到对版本的代码片段」，定位更窄、接入更轻。
源码直连（让 agent 自己 cat README） —— 能跑，但 token 极浪费；Context7 做了检索 + 切片 + 版本匹配。
Cursor 内置 @Library / Codebase 索引 —— Cursor 自己的索引基于你当前项目代码；Context7 补的是「项目外的库文档」，两者可叠加。

一句话推荐结论

给 Cursor / Claude Code / OpenCode 用户加一个 60 秒就能装好的 MCP server，等于把模型的「训练截止日」当场推到当前主版本号；写新项目、跨大版本升级、接入冷门库时性价比最高，其余场景属于「装了不亏、不装也行」。