首页
/ Context7 MCP Server：让 LLM 与 AI 编程编辑器用上最新、真实的库文档

Context7 MCP Server：让 LLM 与 AI 编程编辑器用上最新、真实的库文档

2026-09-03 17:55:53作者：庞眉杨Will
context7
Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors
项目地址：https://gitcode.com/gh_mirrors/co/context7

本文基于 Context7 仓库的官方文档（含阿拉伯语版本 i18n/README.ar.md 与主 README README.md）系统讲解 Context7 MCP Server 的核心价值、各客户端安装配置、两个 MCP 工具的参数细节，并结合 MCP 服务器源码 深入其工具注册、参数容错、API 调用与部署实现，帮你把"实时库文档"真正接入自己的 AI 编程工作流。

一、为什么需要 Context7：解决 LLM 的"过期文档"问题

大语言模型的库知识来自训练数据，因此在使用 Context7 之前，开发者普遍会遇到三类典型问题（原文档 "Without Context7" 一节）：

  • 代码示例基于一年多前的训练数据，已经过期；
  • 模型"幻觉"出根本不存在的 API；
  • 针对旧版本包给出泛泛的回答。

Context7 的做法是：直接从源头提取最新的、版本相关的文档与代码示例，并直接注入到模型的 prompt 中，而不是让模型凭记忆作答。使用方式非常轻量——在 Cursor 等支持 MCP 或 Rules 的客户端里，只需在自然语言请求末尾加上 use context7，例如（原文档给出的阿拉伯语示例及其对应含义）：

أنشئ مشروع Next.js بسيط باستخدام app router. use context7
（创建一个使用 app router 的简单 Next.js 项目。use context7）

أنشئ سكربت لحذف الصفوف التي تكون فيها المدينة فارغة "" باستخدام بيانات اعتماد PostgreSQL. use context7
（写一个使用 PostgreSQL 凭据删除"城市"字段为空的行的脚本。use context7）

原文档将使用流程归纳为三步：1) 像平常一样写请求；2) 在请求中加上 use context7；3) 直接得到可运行的代码——无需切换标签页，不产生幻觉 API，不生成过期代码。

从源码看，MCP Server 启动时会向客户端声明一段服务器级 instructions（packages/mcp/src/index.ts），明确告诉 Agent："只要用户询问任何库、框架、SDK、API、CLI 工具或云服务——哪怕你自认为已经知道答案——也优先调用本服务器获取文档"，同时划定了不适用的场景（重构、从零写脚本、业务逻辑调试、代码审查、通用编程概念）。这段声明正是"加一句 use context7 就能触发"行为在协议层面的落地。

二、安装要求

原文档"البدء"（Getting Started）一节列出的前置条件：

  • Node.js 18.0.0 或更高版本；
  • Cursor、Devin Desktop、Claude Desktop 或任何其它 MCP 客户端。

需要补充说明的是：当前仓库中 MCP 包的 packages/mcp/package.json 声明的 engines 为 node >= 20.18.1，因此实际部署时建议使用较新的 Node LTS 版本以规避兼容性问题。

三、各客户端安装配置（完整继承原文档）

以下配置均摘自原文档，可复制使用。所有 stdio 方式的核心都是同一条命令：npx -y @upstash/context7-mcp@latest，它对应 npm 包 @upstash/context7-mcp 的 bin 入口 context7-mcp（见 packages/mcp/package.json 的 bin 字段）。

3.1 通过 Smithery 安装（Claude Desktop 自动配置）

npx -y @smithery/cli install @upstash/context7-mcp --client claude

仓库中的 packages/mcp/smithery.yaml 声明了 Smithery 集成配置：startCommand.type 为 http，且"无需任何配置项"（exampleConfig: {}），这解释了为什么该安装路径不需要额外参数。

3.2 Cursor

进入 Settings -> Cursor Settings -> MCP -> Add new global MCP server，或直接把以下内容写入 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

3.3 使用 Bun

{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

3.4 使用 Deno

{
  "mcpServers": {
    "context7": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-net", "npm:@upstash/context7-mcp"]
    }
  }
}

3.5 Devin Desktop

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

3.6 VS Code

{
  "servers": {
    "Context7": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

3.7 Zed（可携带 API Key）

{
  "context_servers": {
    "Context7": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

这个 --api-key 参数有源码依据：packages/mcp/src/index.ts 中通过 commander 注册了 --api-key <key> 选项，注释说明其作用与设置环境变量 CONTEXT7_API_KEY 等价（index.ts：stdioApiKey = cliOptions.apiKey || process.env.CONTEXT7_API_KEY）。API Key 用于提升匿名访问的速率限制。

3.8 Claude Code

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest

3.9 Claude Desktop / BoltAI

{
  "mcpServers": {
    "Context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

3.10 Copilot Coding Agent（托管 HTTP 端点）

在 Copilot Coding Agent 设置的 MCP configuration 段（Repository -> Settings -> Copilot -> Coding agent -> MCP configuration）中添加：

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "tools": ["query-docs", "resolve-library-id"]
    }
  }
}

这是原文档中唯一的远端托管 HTTP 接入方式，不需要本地 Node 环境。该地址与源码常量一致：packages/mcp/src/lib/constants.ts 定义 MCP_RESOURCE_URL = "https://mcp.context7.com"，而本地以 --transport http 启动时，index.ts 注册的正是 /mcp 匿名访问路由（/mcp/oauth 则要求认证），两者端点语义相同。配置中的 tools 字段白名单即后文详述的两个工具。

3.11 Windows

{
  "mcpServers": {
    "github.com/upstash/context7-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

四、Docker 部署

原文档给出最简 stdio 镜像方案：

Dockerfile：

FROM node:18-alpine
WORKDIR /app
RUN npm install -g @upstash/context7-mcp@latest
CMD ["context7-mcp"]

构建镜像：

docker build -t context7-mcp .

客户端配置：

{
  "mcpServers": {
    "Context7": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "context7-mcp"],
      "transportType": "stdio"
    }
  }
}

仓库内另有一份更贴近工程实践的多阶段构建 Dockerfile：packages/mcp/Dockerfile。它先用 node:lts-alpine 构建阶段 pnpm --filter @upstash/context7-mcp build，生产阶段只拷贝 dist 产物，并默认以 HTTP transport、8080 端口启动（Dockerfile）：

CMD ["node", "dist/index.js", "--transport", "http", "--port", "8080"]

这印证了源码中的双 transport 设计：packages/mcp/src/index.ts 通过 --transport <stdio|http> 切换，默认 stdio；--port 默认 3000，且在 stdio 模式下传 --port 会被直接拒绝（L70-L73），http 模式下传 --api-key 同样被拒绝（L63-L68，HTTP 层走请求头认证）。启动时若端口被占用，会自动尝试 port+1，最多 10 次（index.ts）。

五、两个 MCP 工具深度解析

原文档"الأدوات المتوفرة"（Available Tools）一节定义了 Server 对外暴露的两个工具，这也是整个 Context7 工作流的骨架：先解析库 ID，再按 ID 取文档。

5.1 resolve-library-id：把库名解析为 Context7 ID

作用：将通用的库/产品名转换为 Context7 兼容的库 ID，并返回匹配的库列表。参数（原文档标注均为必填）：

参数 必填 说明
query 是 用户的问题或任务，用于按相关性对结果排序
libraryName 是 要搜索的库名（建议用官方写法，如 Next.js 而非 nextjs）

源码中该工具的注册与详细描述见 packages/mcp/src/index.ts。描述里给出了每个结果包含的字段（Library ID、Name、Description、Code Snippets 数量、Source Reputation、Benchmark Score、可用版本列表）以及选型流程：名称相似度 > 描述相关性 > 文档覆盖度（Code Snippet 数）> 来源声誉 > Benchmark Score；并限制"同一问题最多调用 3 次"。其标注为只读（readOnlyHint: true）且幂等（idempotentHint: true）。

5.2 query-docs：按 ID 拉取最新文档

作用：使用 Context7 兼容 ID 提取库文档。参数：

参数 必填 说明
libraryId 是 精确的 Context7 兼容 ID，如 /mongodb/docs、/vercel/next.js
query 是 要获取的相关文档的问题或任务

源码见 packages/mcp/src/index.ts。描述中额外强调：libraryId 必须来自 resolve-library-id 的结果，除非用户已经直接给出 /org/project 或 /org/project/version 形式的 ID（此时可跳过解析步骤）；query 应聚焦单一概念，跨多个概念时拆成多次调用。

5.3 源码纵深：参数容错与 API 调用链

参数别名容错（aliasArgs）。 这是原文档没有、但源码中很关键的一个健壮性细节：LLM 客户端经常把工具描述里的措辞当参数名回显，导致 Zod 校验直接失败。Server 用 z.preprocess 在校验前重写别名（index.ts）：

  • 全局别名：query 可接受 userQuery、question；
  • query-docs 专属：libraryId 可接受 context7CompatibleLibraryID、libraryID、libraryName。

API 调用链。 工具处理器最终调用 packages/mcp/src/lib/api.ts 中的两个函数：

  • searchLibraries -> GET {CONTEXT7_API_BASE_URL}/v2/libs/search?query=&libraryName=（api.ts）；
  • fetchLibraryContext -> GET {CONTEXT7_API_BASE_URL}/v2/context?query=&libraryId=（api.ts）。

CONTEXT7_API_BASE_URL 默认为 https://context7.com/api，可用环境变量 CONTEXT7_API_URL 覆盖（constants.ts）。所有 API 调用带 60 秒超时（API_TIMEOUT_MS = 60_000，api.ts）。另外，该仓库只托管 MCP Server 源码，API 后端、解析引擎与爬虫引擎均为私有组件、不在此仓库中（见主 README.md 的 Disclaimer 第 2 条）。

请求头与鉴权。 packages/mcp/src/lib/encryption.ts 的 generateHeaders 会为每次 API 调用附加来源标记（X-Context7-Source: mcp-server）、服务器版本、客户端 IDE/版本、transport 类型、会话 ID；若设置了 API Key，则以 Authorization: Bearer <key> 发送。HTTP transport 模式下，认证头可来自 Authorization、X-Context7-API-Key、Context7-API-Key、X-API-Key 等多个位置（index.ts）。

六、本地开发与调试

原文档"التطوير"（Development）一节的完整流程：

pnpm i
pnpm run build

本地客户端配置（指向未打包的源码入口）：

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["tsx", "/path/to/folder/context7-mcp/src/index.ts"]
    }
  }
}

用 MCP Inspector 测试：

npx -y @modelcontextprotocol/inspector npx @upstash/context7-mcp@latest

结合仓库可补充几个细节：

  • 仓库的 build 脚本实际是 tsc && chmod 755 dist/index.js（packages/mcp/package.json），start 脚本为 node dist/index.js --transport http（L15），即本地跑 HTTP 服务只需 pnpm run start；
  • stdio 进程在 stdin 结束/关闭或收到 SIGHUP 时自动退出（index.ts），并在启动握手时捕获客户端版本信息用于上报；
  • 集成测试见 packages/mcp/test/integration.test.ts，可参考其中的客户端接入方式。

七、故障排查（Troubleshooting）

完整继承原文档"استكشاف الأخطاء"一节的三类问题与解法：

7.1 ERR_MODULE_NOT_FOUND

改用 bunx 替代 npx：

{
  "mcpServers": {
    "context7": {
      "command": "bunx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

7.2 ESM 相关错误

尝试加上实验性 VM 模块参数并固定版本：

{
  "command": "npx",
  "args": ["-y", "--node-options=--experimental-vm-modules", "@upstash/context7-mcp@1.0.6"]
}

7.3 MCP 客户端通用错误排查顺序

  1. 移除 @latest 后缀；
  2. 尝试 bunx；
  3. 尝试 deno；
  4. 确认使用 Node v18 或更新版本（结合 3.11 节 Windows 配置与 7.2 节 ESM 参数）。

源码层面的补充依据，可帮助快速定位错误来自哪一层：

  • 上游 API 返回 429/404/401 时，parseErrorResponse 会生成明确的文案：429 提示速率限制/配额（无 Key 时引导去创建免费 API Key），404 提示库 ID 不存在，401 提示 Key 无效且"应以 ctx7sk 前缀开头"（api.ts）。看到这些文案即可判断问题在鉴权/配额层而非客户端配置层；
  • 企业网络下可通过 HTTPS_PROXY/HTTP_PROXY（大小写变体均支持）走代理，并可用 NODE_EXTRA_CA_CERTS 注入自定义 CA（api.ts）；
  • 工具调用若返回"未找到库"之类文本而非崩溃，是因为 searchLibraries/fetchLibraryContext 全部捕获异常并返回错误文本（api.ts、L178-L182），所以"工具能调通但内容不对"多半是 libraryId 或 query 问题。

八、注意事项：免责与许可证

  • 社区贡献内容免责（原文档"إخلاء مسؤولية"）：Context7 收录的项目由社区贡献，官方不保证全部库文档的准确性与安全性；发现可疑内容应通过项目页的"Report"按钮举报。
  • 许可证：MIT（LICENSE）。
  • 多语言文档：本仓库 i18n/ 目录提供了 15 种语言的 README，包括 简体中文、繁體中文、日本語、한국어、Русский 等，内容与本文依据的 阿拉伯语版 对应，可按需切换阅读；更细的 API 参考、CLI 参考与 30+ 客户端手动安装指南见仓库内 docs/ 文档站（如 installation.mdx、api-guide.mdx）。
context7
Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors
项目地址：https://gitcode.com/gh_mirrors/co/context7
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
903
1.82 K
docsdocs
暂无描述
Markdown
888
5.78 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
527
590
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.51 K
1.01 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.33 K
1.45 K
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
540
384
flutter_flutterflutter_flutter
本仓库是 Flutter SDK 与 Flutter Engine 的 OpenHarmony 适配版本，由 CPF-Flutter 团队维护。开发者可使用熟悉的 Flutter 技术栈开发 OpenHarmony 应用，3.35.7 及以后的适配版本可基于本仓库源码构建支持 OpenHarmony 的 Flutter Engine。
Dart
1.17 K
341