使用 MCP 服务器，把乐鑫文档接入 AI 工作流

为什么使用 MCP

模型上下文协议 (MCP) 是一项让 AI Agent 连接外部数据源、工具和工作流的开放标准。有了 MCP，AI Agent 不再靠训练数据或搜索结果"猜答案"，而是直接从真实、最新的上下文中获取信息并采取行动。

乐鑫文档 MCP 服务器将这一标准引入乐鑫官方文档体系。在 Cursor、VS Code、Claude Code 或其他支持 MCP 的编辑器中完成安装 MCP 服务器后，AI Agent 可以直接查询乐鑫官方文档。这意味着：

文档检索无需离开编辑器 --- 通过 AI Agent 检索完整的乐鑫文档库，无需跳转到浏览器或手动翻看 PDF；
更快拿到准确答案 --- 获取基于官方文档的实现方案、代码示例和报错修复建议，告别过时的搜索结果和可能滞后的模型训练数据；
减少 AI 幻觉 --- 代码建议和技术回答直接来自最新的乐鑫官方文档，而非模型凭空生成的内容。

MCP 服务器能力

乐鑫文档 MCP 服务器向 AI Agent 提供以下工具：

|--------------------------------------------|-----------------------------------------------------|
| 工具 | 描述 |
| search_espressif_sources (query, language) | 对乐鑫最新官方中英文文档执行语义检索，返回最相关的文本片段和来源链接，为 AI 助手提供官方参考资料。 |

MCP 服务器与乐鑫文档 AI 助手共享同一套知识源，覆盖：

芯片及模组规格书 (Datasheet)
技术参考手册 (TRM)
硬件设计指南 (HDG)
SDK 文档，包括最新版 ESP-IDF 编程指南
产品变更通知 (PCN)、公告及证书
乐鑫博客文章和技术文章
部分停产 (EOL) 或不推荐用于新设计 (NRND) 产品的文档
部分 M5Stack 文档

MCP 服务器 vs 文档 AI 助手

MCP 服务器和乐鑫文档 AI 助手都能访问最新的乐鑫文档，但适用场景不同。

|-------------|---------|----------|
| 使用场景 | MCP 服务器 | 文档 AI 助手 |
| 集成到 IDE 工作流 | ✅ | ❌ |
| 直接修改项目代码 | ✅ | ❌ |
| 基于文档的结构化推理 | ✅ | ⚠️ 有限 |
| 快速文档问答 | ⚠️ | ✅ |
| 了解与探索 | ⚠️ | ✅ |
| 非技术用户 | ❌ | ✅ |

总结：

如需在开发流程中使用文档，使用 MCP 服务器。
如果查阅文档了解产品，使用文档 AI 助手。

如何安装 MCP 服务器

打开乐鑫文档 AI 助手组件：
点击组件右上角的 "MCP 服务器"，选择要使用的编辑器，按对应说明操作。

在终端中运行以下命令验证：

复制代码

xdg-open "cursor://test"

如果没有任何反应或出现错误提示，说明 URL 协议处理程序尚未注册。这是系统层面的问题，需要先解决此问题，才能通过浏览器添加 MCP 服务器。

在自动打开的 Cursor 设置页面中，点击 "Install MCP Server?" 下方的 "Install"。

Cursor

打开 Cursor。
在文档 AI 助手组件的 "MCP 服务器" 下点击 "Add to Cursor"（添加到 Cursor）。浏览器可能会询问是否允许打开 Cursor，点击允许即可。

如果点击 "Add to Cursor" 无反应，可以手动将以下配置写入 .cursor/mcp.json：

复制代码

{ 
  "mcpServers": { 
    "espressif-docs": { 
      "url": "https://mcp.espressif.com/docs" 
    } 
  } 
}

保存后重启 Cursor，打开设置页面，按照第四步继续操作。

在 Linux 系统中，如果未注册 cursor:// URL 协议处理程序，在浏览器中点击 "Add to Cursor" 或修改 *.*cursor/mcp.json 配置文件可能没有任何反应。

在终端中运行以下命令验证：

复制代码

xdg-open "cursor://test"

如果没有任何反应或出现错误提示，说明 URL 协议处理程序尚未注册。这是系统层面的问题，需要先解决此问题，才能通过浏览器添加 MCP 服务器。

在自动打开的 Cursor 设置页面中，点击 "Install MCP Server?" 下方的 "Install"。

安装完成后，点击 "Connect"，允许 Cursor 打开外部网页，按屏幕提示完成身份验证。

注意：微信身份验证功能尚未实现，将在后续版本中启用。

VS Code

打开 VS Code。
在"MCP 服务器"下点击 "Add to VS Code"（添加到 VS Code）。浏览器可能会询问是否允许打开 VS Code，点击允许。

如果点击 "Add to VS Code" 无反应，可以手动将以下配置写入 .vscode/mcp.json：

复制代码

{ 
  "servers": { 
    "espressif-docs": { 
      "url": "https://mcp.espressif.com/docs" 
    } 
  } 
}

保存文件，点击新加配置上方的 "启动"启动 MCP 服务器，按照第四步继续操作。

在 Linux 系统中，如果未注册 vscode:// URL 协议处理程序，在浏览器中点击 "Add to VS Code" 或修改 .vscode/mcp.json配置文件可能没有任何反应。

在终端中运行以下命令验证：

复制代码

 xdg-open "vscode://test"

如果没有任何反应或出现错误提示，说明 URL 协议处理程序尚未注册。这是系统层面的问题，需要先解决此问题，才能通过浏览器添加 MCP 服务器。

在 MCP 安装页面点击 "安装"

允许 VS Code 打开外部网页，按屏幕提示完成身份验证。
注意：微信身份验证功能尚未实现，将在后续版本中启用。

验证完成后，可以在扩展 > MCP 服务器 -- 已安装 下看到已安装的 MCP 服务器。

Claude Code

在"MCP 服务器"下点击 "Add to Claude Code"（添加到 Claude Code）复制安装命令。
在终端执行复制的命令。

安装成功后，终端会打印以下信息：

复制代码

Added HTTP MCP server espressif-docs with URL: https://mcp.espressif.com/docs to local config
File modified: /Users/user/.claude.json [project: /Users/user]

完成身份验证：注意：微信身份验证功能尚未实现，将在后续版本中启用。

在终端中运行 claude 以启动 Claude Code
输入/mcp 打开 MCP 管理面板
选择 MCP 服务器，然后选择 Authenticate
浏览器窗口自动打开后，按屏幕提示完成身份验证

Claude Desktop

将以下配置添加到 Claude Desktop 的配置文件中，安装文档 MCP 服务器：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
"espressif-docs": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.espressif.com/docs"]
}
}
}

保存文件并重启 Claude Desktop。程序会自动打开浏览器窗口，按屏幕提示完成身份验证。
注意：微信身份验证功能尚未实现，将在后续版本中启用。

验证成功后，MCP 服务器会出现在 "Settings > Developer > Local MCP servers" 中。

示例提示词 (Prompt)

以下示例提示词展示了 MCP 服务器的不同使用场景：

生成代码

我有 ESP32-S3-Box-3 开发套件和一个外接 LED 灯。我想在 ESP-IDF 环境下用 C 语言写一个应用程序，通过 LEDC PWM 外设来控制 LED 的亮度。请提供详细的指南和代码示例，并说明如何配置 GPIO 以及相关的定时器参数。

代码审校

对照 ESP-IDF SPI 主机驱动程序文档审校这段 SPI 初始化代码，找出错误的 API 用法、已废弃的函数、缺少的配置步骤。

排查报错

我遇到了这个报错："CMakeError at run_serial_tool.cmake:67 (message): idf.py: error: argument --port: expected one argument"，请在ESP-IDF文档中查一下原因并给出解决方案。

统一代码风格

请按照乐鑫 IoT 开发框架风格指南更新这段代码。

生成配置文件

根据 ESP-IDF 分区表文档，为 4 MB Flash 生成一个分区表 CSV，要求：1 MB factory app、512 KB OTA_0、512 KB OTA_1、16 KB NVS。

更新配置选项

查阅乐鑫文档，找到 ESP32-C3 推荐的 I2C 管脚，并修改管脚配置项 I2C_MASTER_SCL 和 I2C_MASTER_SDA。

迁移 ESP-IDF 版本

我的项目当前用 ESP-IDF v5.1。请参考 v5.2 和 v5.3 的迁移指南，列出影响 UART 和 I2C 驱动的重大 API 变更，并更新 main/comm.c 中的相关调用。

最佳实践

确认工具调用已触发。每次提问后，检查编辑器中是否出现了 MCP 工具调用的标识。如果没有，说明 AI Agent 可能在用训练数据或网络搜索直接作答，而不是查询乐鑫文档。

在提示词中明确说明参考乐鑫文档 。如果 AI Agent 没有自动使用 MCP 服务器，可以在提示词里加上"请参考乐鑫文档"。如果不想每次手动在提示词中说明，也可以在 AGENTS.md 里统一配置：

AGENTS.md

处理 ESP 芯片或 ESP-IDF、ESP-ADF 等 SDK 相关问题时，
请始终主动调用乐鑫文档 MCP 服务器，无需每次单独提醒。

使用限制

乐鑫文档 MCP 服务器目前存在以下限制：

仅限检索 --- MCP 服务器只负责检索文档并将内容传给 AI Agent 作为上下文，不会自行执行代码、修改文件或触发任何操作，这些都由 AI Agent 负责。
仅限公开文档 --- MCP 服务器知识源只覆盖乐鑫公开文档，不包含代码仓库、GitHub Issues、社区论坛、第三方资料、内部文档，以及大部分 EOL 和 NRND 产品的文档。
有调用频率限制 --- 为保证所有用户的正常访问，服务器对每个账号设有以下限制：
每小时最多 40 次请求
每天最多 200 次请求
不适合对话式使用 --- 如果想泛泛提问、浏览特定话题、生成文档总结，建议使用乐鑫文档 AI 助手。

常见问题

1. 使用 MCP 服务器需要联网吗？

需要。MCP 服务器联网后才能正常使用。

2. 需要账号吗？

需要。验证身份时需要使用GitHub 账号或微信账号登录。系统只会保存你的匿名账号 ID，用于限制调用频率，不会存储其他个人信息。 注意：微信身份验证功能尚未实现，将在后续版本中启用。

3. 安装完是否需要手动启动 MCP 服务器？

不需要。MCP 服务器是远程服务，本地没有需要启动的进程。 例外： 如果通过手动编辑 VS Code 的 mcp.json 安装 MCP 服务器，需要点击配置项上方的 Start 按钮打开身份验证页面，详见 VS Code 安装步骤。完成验证后，后续服务器会自动启动。

4. 为什么我已在提示词中说明参考乐鑫文档，但 AI Agent 仍然没有调用乐鑫文档 MCP 服务器？

第一步：在编辑器中确认 MCP 服务器状态正常。

Cursor：进入 Settings > Tools & MCP，查看服务器状态。
VS Code：打开扩展面板，进入 MCP SERVERS -- INSTALLED 查看。
Claude Code：在终端运行 claude mcp list。
Claude Desktop：进入 Settings > Desktop > Developer > Local MCP servers 查看。

如果 MCP 服务器显示为禁用状态，请手动启用。

如果身份验证已过期，请重新验证或重新添加 MCP 服务器。

如果问题无法解决，请提交反馈，附上编辑器中显示的错误信息。

第二步：确认 AI Agent 有权限调用 MCP 工具

Cursor：进入 Settings > Agents > MCP Allowlist。首次调用时 Cursor 会弹窗询问，授权即可。如果没有弹窗，则手动添加工具名，例如 espressif-docs: search_espressif_sources。
VS Code：工具权限按会话管理，每次会话首次调用时会询问。
Claude Code：首次调用时会弹窗确认，选择"始终允许"即可。也可以在启动时通过命令行直接授权：claude --allowedTools mcp__espressif-docs__search_espressif_sources
Claude Desktop：进入 Settings > Customize > Connectors > Desktop > Tool permissions，默认为"Needs approval"（每次调用前询问）。如需免确认，可在此处修改权限设置。

第三步：换个编辑器试试

各编辑器对 MCP 的支持程度不同。如果以上两步都没有解决问题，可以试试其他编辑器。比如， Cursor 用户可以尝试切换成 VS Code 或 Claude Code。

如果切换编辑器后问题依然存在，可能是 MCP 服务器本身的故障。如果切换编辑器后问题依然存在，可能是 MCP 服务器本身的故障。请查看 MCP服务器状态，了解是否有已知问题。

5. MCP 服务器能回答有关停产版本（如 ESP-IDF v4.4）的问题吗？

不能。MCP 服务器知识源只收录最新的 ESP-IDF 版本，已停产版本（如 ESP-IDF v4.4）和非最新版本的文档未包含在内。如果你的项目还在用旧版本，MCP 服务器返回的内容可能与你的 SDK 版本不一致。

6. 为什么 AI 助手链接的是英文文档，而不是中文文档？

MCP 服务器会根据检索语言，在英文或中文文档中检索。如果 AI Agent未指定检索语言，则默认返回英文文档。

每条回复都会附上来源文档的链接，方便您查阅完整内容。

使用 MCP 服务器，把乐鑫文档接入 AI 工作流

为什么使用 MCP

MCP 服务器能力

MCP 服务器 vs 文档 AI 助手

Cursor

VS Code

Claude Code

Claude Desktop

示例提示词 (Prompt)

最佳实践

AGENTS.md

使用限制

常见问题