Context7 MCP Server

什么是 Context7 MCP Server？

Context7 MCP Server 是 Upstash 官方的 Context7 MCP 服务器：它把最新的、对应具体版本的库文档和代码示例拉取到 AI 编程助手的上下文中，让回答使用当前的 API，而不是过时的训练数据。

Context7 由 Upstash 开发。MCP 服务器源码位于 upstash/context7 仓库（MIT 许可），并以 @upstash/context7-mcp 发布在 npm 上；构建文档索引的 API 后端、解析引擎和爬取引擎是私有的。你可以把它作为托管的远程服务器使用，也可以在本地运行；它还提供无需 MCP 的 CLI + Skills 模式。

如何使用 Context7 MCP Server？

最快的方式是使用安装 CLI，需要 Node.js 22.13 或更高版本：

npx ctx7 setup

它会通过 OAuth 登录、生成 API 密钥，并让你在 CLI + Skills 模式和 MCP 模式之间选择。加上 --cursor、--claude 或 --opencode 可指定目标 agent。之后如需撤销，运行 npx ctx7 remove。

手动配置时，使用远程服务器 URL https://mcp.context7.com/mcp，并在 Authorization: Bearer YOUR_API_KEY 请求头中发送密钥。建议在 context7.com/dashboard 免费获取 API 密钥以获得更高的速率限制。若要在本地运行，使用 npx -y @upstash/context7-mcp --api-key YOUR_API_KEY。

Claude Code

远程：

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

Claude Desktop

使用远程服务器时，打开 Settings > Connectors > Add Custom Connector，名称填 Context7，URL 填 https://mcp.context7.com/mcp。使用本地服务器时，在 claude_desktop_config.json 中添加：

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

Cursor

添加到 ~/.cursor/mcp.json（README 中也提供一键安装按钮）：

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

VS Code

添加到 .vscode/mcp.json：

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

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }

其他 30 多个客户端的配置说明见 Context7 客户端文档。

Context7 MCP Server 的主要功能

• 直接从库的源头获取最新文档和代码示例，并放入提示词中。
• 感知版本：在提示中写明版本（如 “Next.js 16 proxy”），Context7 会匹配对应的文档。
• 使用 /supabase/supabase、/vercel/next.js 这样的库 ID 可跳过搜索步骤。
• 同时提供托管远程端点和本地 npm 包，适配任何 MCP 客户端。
• CLI + Skills 模式（ctx7 library、ctx7 docs），适合不想运行 MCP 的 agent。
• 通过 npx ctx7 setup 一条命令为 Cursor、Claude Code 和 OpenCode 完成配置。
• 库维护者可以把自己的项目提交到索引中。

Context7 MCP Server 工具

该服务器的工具非常精简，只有两个，通常按顺序调用：

• resolve-library-id 把普通库名（“supabase”、“next.js”）解析为 Context7 兼容的 ID。参数为 libraryName 和你的 query，后者用于对匹配结果排序。
• query-docs 根据给定的 libraryId 和 query 返回文档和示例。可选参数 language 会优先排列你所用语言的代码示例。

如果你已经知道库 ID，把它写进提示词，agent 就可以直接调用 query-docs。

Context7 MCP Server 的使用场景

• 针对快速迭代的框架编写代码：“Create a Next.js proxy that checks for a valid JWT in cookies and redirects unauthenticated users to /login. use context7”
• 平台配置：“Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7”
• 查找具体 API：“Show me the Supabase auth API for email/password sign-up.”
• 升级时锁定特定版本，例如从旧版本迁移时询问 Next.js 16 的行为。
• 通过规则让 Context7 自动生效，例如在 Cursor Rules 或 CLAUDE.md 中加入 “Always use Context7 when I need library/API documentation, code generation, setup or configuration steps”。

Context7 MCP Server 与替代方案对比

• DeepWiki MCP Server： 基于自动生成的 wiki 页面回答关于 GitHub 仓库的问题。Context7 则专注于为编程提示提供经过整理、对应具体版本的库文档和代码片段。
• agent 内置的网页搜索： 通用但缺乏结构。Context7 返回的是针对特定库和版本、已经解析好的文档，通常消耗更少的 token，也更少走弯路。
• 远程与本地 Context7： 远程 URL 不需要在本机安装 Node.js；本地 @upstash/context7-mcp 包仍会调用 Context7 API，因此两种方式都需要网络访问。

Context7 MCP Server 常见问题排查

• 触发速率限制： 在 context7.com/dashboard 创建 API 密钥，并通过 Authorization: Bearer（远程）或 --api-key（本地）发送。
• 401 Unauthorized： 检查密钥是否正确且以 ctx7sk 开头，并确认你的传输方式使用了正确的请求头或参数。
• 某个库返回 404： ID 必须形如 /owner/repo 或 /owner/repo/version。先运行 resolve-library-id，并确认该库在 context7.com 上存在。
• 本地服务器无法启动： 用 node --version 确认 Node.js 版本足够新，尝试 @upstash/context7-mcp@latest，遇到 ERR_MODULE_NOT_FOUND 时用 bunx 代替 npx。改用远程 URL 可以完全避开 Node.js 问题。
• Claude Code 识别不到它： 运行 claude mcp list 检查服务器，查看 claude mcp logs context7，或删除后重新添加。可用 curl https://mcp.context7.com/ping 测试连通性。