为 Cursor 和 Claude Code 配置 Context7，并确认它真的被使用

智能体给出一个你没见过的库方法时，先问它是从哪儿来的。示例看着合理，却可能属于这个包的另一个版本，甚至在 API 里根本不存在。要核实，只能看项目实际使用的那个库的文档。

Context7 负责查找库文档，把相关片段交给智能体。它可以连接 Cursor 和 Claude Code，为 API 开发提供出处；据此写出的代码，仍然要在你的应用里验证。

• Context7 概述

下面先讲本地客户端的配置，再给一个检查请求，用来分辨智能体是真的查了文档，还是凭记忆作答。这些步骤我们已对照官方文档核对过；我们没有连接你的账号，也没有测试你的配置。

什么时候有用

先挑一个依赖具体库的任务：路由配置、表单处理、ORM 查询，或者通过 SDK 上传文件。这类任务需要知道有哪些方法、接受什么参数、文档承诺了什么行为。

如果只是改个错字，或者梳理自己的业务逻辑，去查外部库文档多半帮不上忙。先弄清楚缺的是哪方面的知识。

不要一上来就要求“接入所有文档”。提一个具体问题，让查到的资料来回答。

文档查询怎样工作

MCP 连接主要有两个工具：`resolve-library-id` 查找库标识符，`query-docs` 按问题取回资料。标识符已知时，第一步可以跳过。

• 集成文档

任务和包版本
    ↓
选择正确的库
    ↓
查询文档答案
    ↓
与项目代码对照
    ↓
修改并验证结果

每一步都可以单独检查。库选错了，示例改写得再整齐也没用；文档找对了，也不代表代码已经正确接入你的应用。

安装前准备

你需要装好 Cursor 或 Claude Code，能联网，并且有可用的 Node.js（带 npm/npx）来运行配置命令。ctx7 安装器要求 Node.js 18 或更高版本；新环境建议装仍在支持期内的 LTS。

• CLI 要求

在普通终端检查：

node --version
npx --version

如果提示找不到命令，先在准备运行安装器的环境里配好 Node.js。macOS、Windows、WSL 是不同的环境，以你实际使用的终端为准。

如果 Context7 已经连接过，重装之前先看一下现有配置。同一个服务有两条认证方式不同的记录，你就很难判断智能体走的是哪一条。

连接 Claude Code

终端运行：

npx ctx7 setup --claude

安装器会引导你完成 OAuth 登录，并让你选择连接方式。按提示操作，在浏览器里完成授权即可。这是 Context7 文档为 Claude Code 给出的流程。

• Claude Code 官方集成指南

有两种模式：MCP 和 CLI + Skills。前者把服务器的工具交给智能体，后者让智能体按技能说明调用 ctx7 命令。要做下文的检查，请选 MCP，这样能在记录里看到带名称的工具调用。CLI 设置默认全局生效，`--project` 可限定当前项目。

• 设置模式

完成后打开 Claude Code，运行 `/mcp`，可以看到可用的服务器及其状态。

• MCP 管理

如果选的是 CLI + Skills，要找的是实际执行过的 ctx7 命令，而不是 MCP 服务器。两种模式访问文档的路径不同。

连接 Cursor

Cursor 有单独的命令：

npx ctx7 setup --cursor

完成授权；如果想复现本文的检查请求，请选择 MCP。

• Cursor 指南

要手动配置，打开 Cursor 的 MCP 设置。全局配置文件是 `~/.cursor/mcp.json`，项目配置文件是 `.cursor/mcp.json`。Context7 文档给出的 HTTP 配置如下：

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

`YOUR_API_KEY` 处填你账号里的密钥。这段配置与官方客户端说明一致。如果文件已经存在，把 context7 加到 mcpServers 里，其他连接保持不动。

• 官方客户端说明

不要把个人密钥提交到共享仓库。第一次手动配置，用个人配置文件更省事。OAuth 使用不同地址 `https://mcp.context7.com/mcp/oauth`，不要混用两种认证。

• 认证方式

一般用自动设置就够了。需要检查配置或自己管理配置时，再改用手动方式。

确认智能体真的使用了 Context7

先用一个你熟悉的库，来源不对时更容易看出来。如果项目里装了 Zod，可以发送：

找出项目安装的 Zod 版本。使用 Context7 查明该版本如何验证邮箱，并在不抛异常的情况下返回验证结果。先选择库，再查文档。展示标识符、来源链接和短示例。如果文档不能确认对应版本，明确说明。不要修改文件。

这是练习用的请求，本文没有收录服务的实际输出。项目里没有 Zod 的话，换一个已安装且你熟悉的包，问一个具体的 API 小问题。

如果标识符是你自己提供的，记录里没有 `resolve-library-id` 很正常，要看的是对正确的库是否查询成功。如果工具报了错，之后的回答再自信，也不能算查到了文档。

为什么版本比示例是否可信更重要

在请求里写明版本可以缩小范围，但还要和返回的资料逐一核对。只有查询结果里包含对应版本时，才能使用该版本的库标识符；请从实际返回的列表中选择。

• 库与版本查询

假设项目用的是旧的主版本，而示例是为新版本写的。不要马上改动整个项目去迁就示例，先确认已安装的版本是否支持这个操作。升级依赖是另一个决定，牵涉的范围更大。

可以按这个顺序来：

1. 从项目文件确定版本。
2. 找到文档中的操作方法。
3. 检查示例是否适用。
4. 做有限修改并执行相应检查。

如果版本确认不了，就直接打开该版本的官方文档或迁移指南。一个工具没查到，不代表这个库没有解决办法。

每次都要写 use context7 吗？

测试连接时，明确写上 `use context7` 很方便。自动设置也可能顺带安装一个文档查询技能。

• 调用方式

日常工作中，更有用的做法是写明什么时候该用它：

如果方案依赖外部库 API，先确定项目安装版本，
再通过 Context7 查找对应文档。
来源不可用或版本无法确认时，说明情况，
并直接查看官方文档。

这条规则是我们的建议，可以放进 CLAUDE.md 或 Cursor 的项目规则。它规定了什么时候查文档、查不到时怎么办，同时不要求每改一处文字都去外部搜索。

• CLAUDE.md

Context7 不工作时怎么办

先看请求卡在哪一步。把整个客户端重装一遍，通常找不出原因。

前四行是访问层面的问题，后两行是查询和结果应用的问题。技术细节见故障排查。

• 故障排查

Cursor Cloud Agents 用的是另一套 MCP 配置。本地能用，不代表云端运行时也能用，请按 Cloud Agents 指南单独配置。

• Cloud Agents 指南