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

智能体提出陌生的库方法时，应问清来源。看似合理的示例可能属于另一版本，甚至不符合 API。核查需要项目实际使用的库文档。

Context7 查找库文档，并将相关片段提供给智能体。 它可连接 Cursor 和 Claude Code，为 API 开发提供来源；生成的代码仍需在应用中验证。Context7 概述。

• Context7 概述

本文介绍本地客户端配置，并提供一个检查请求，用于区分真实查询与凭记忆回答。指令已对照官方资料；没有连接你的账号或进行账号内实测。

什么时候有用

从依赖具体库的任务开始：路由配置、表单处理、ORM 查询或 SDK 文件上传。这些场景需要知道方法是否存在、接受哪些参数、承诺什么行为。

改错字或分析自己的业务逻辑时，外部库搜索可能无帮助。先明确缺少什么知识。

不要先要求“接入所有文档”，而应提出来源必须回答的具体问题。

文档查询怎样工作

MCP 连接主要使用两个工具：`resolve-library-id` 找库标识符，`query-docs` 根据问题获取资料。已知标识符时，可跳过第一次查找。集成文档。

• 集成文档

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

每一步都可单独检查。把示例改写得再整齐，也不能补救选错库；找到正确文档也不表示已正确接入应用。

安装前准备

需要已安装 Cursor 或 Claude Code、网络，以及带 npm/npx 的 Node.js。ctx7 安装器要求 Node.js 18 或更高；新环境宜选择仍受支持的 LTS。CLI 要求。

• CLI 要求

在普通终端检查：

node --version
npx --version

如果找不到命令，先在实际运行安装器的环境配置 Node.js，可能是 macOS、Windows 或 WSL。

如果已有 Context7，先检查配置再安装。不同认证方式的重复连接会让你难以判断智能体究竟用了哪个。

连接 Claude Code

终端运行：

npx ctx7 setup --claude

安装器引导 OAuth 登录并选择连接方式。按提示在浏览器完成授权。这是 Claude Code 官方集成指南给出的起始流程。

• Claude Code 官方集成指南

可选 MCP 与 CLI + Skills。前者提供服务器工具，后者按技能说明调用 ctx7 命令。为观察下文工具调用，选择 MCP。CLI 设置默认全局生效，`--project` 可限定当前项目。设置模式。

• 设置模式

完成后，在 Claude Code 使用 `/mcp` 查看可用服务器和状态。MCP 管理。

• MCP 管理

如果选了 CLI + Skills，应检查实际 ctx7 命令，而不是是否存在 MCP 服务器。两者是不同文档访问路径。

连接 Cursor

使用专门命令：

npx ctx7 setup --cursor

完成授权，选择 MCP 以复现本文检查流程。Cursor 指南。

• Cursor 指南

手动配置时打开 Cursor 的 MCP 设置。全局文件为 `~/.cursor/mcp.json`，项目文件为 `.cursor/mcp.json`。官方 HTTP 示例：

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

`YOUR_API_KEY` 是账号密钥占位符，配置见官方客户端说明。在已有文件的 mcpServers 中添加 context7，同时保留其他连接。

• 官方客户端说明

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

• 认证方式

自动设置通常足够。需要理解或自行管理配置时，再采用手动方式。

确认智能体真的使用了 Context7

先选择熟悉的库，便于发现错误来源。若项目安装了 Zod，可发送：

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

这是教学请求，不是服务实际输出记录。没有 Zod 时，换成已安装且熟悉的包，并问一个小型 API 问题。

提前提供了标识符时，没有 `resolve-library-id` 很正常；关键是查询正确库。工具报错后再给出流畅回答，不等于查询成功。

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

请求中写版本有助于缩小范围，但仍要与返回资料核对。Context7 CLI 仅在结果提供时使用带版本标识符，应从实际返回列表选择。库与版本查询。

• 库与版本查询

若项目是旧主版本，示例面向新版本，不要立刻改整个项目来适配。先确认已安装版本是否支持所需操作。升级依赖是另一个决定，可能影响更多部分。

建议顺序：

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

无法确认版本时，直接打开该版本官方文档或迁移指南。一个工具没找到，不代表库没有解决方案。

每次都要写 use context7 吗？

明确写 `use context7` 适合测试连接。自动设置也可能安装文档查询技能。调用方式。

• 调用方式

日常项目更适合定义触发条件：

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

这是建议规则，可放入 CLAUDE.md 或 Cursor 项目规则。它规定查询时机与失败后的处理，不要求每次改文字都外部搜索。

• CLAUDE.md

Context7 不工作时怎么办

检查请求停在哪个阶段。重装整个客户端通常不能解释原因。

前四项是访问配置问题，后两项是查询与应用问题。技术细节见故障排查。

• 故障排查

Cursor Cloud Agents 使用自己的 MCP 配置。本地编辑器能用，不代表云端运行能用，需按 Cloud Agents 指南单独配置。

• Cloud Agents 指南