ESP-IDF Tools 本地 MCP Server：通过 AI 助手构建、烧录与管理项目

乐鑫科技 Espressif

22人浏览 · 2026-05-15 12:51:51

乐鑫科技 Espressif · 2026-05-15 12:51:51 发布

ESP-IDF v6.0 引入了 Tools 本地 MCP Server，这一功能可让 Cursor、Claude Code 等 AI 客户端直接控制你的项目 —— 包括设置目标芯片、构建、烧录以及检查项目状态。本文将介绍其工作原理，并一步步带你完成配置。

背景

乐鑫近期推出了文档 MCP Server，这是一项远程服务，可让 AI Agent 在编辑器中直接访问官方 Espressif 文档。它能够基于真实、最新的官方文档，协助完成代码生成、代码审查、故障排查以及迁移工作。

但文档检索只是整个流程的一半。即使 AI 已经知道该怎么做，它仍无法真正执行操作：设置目标芯片、构建固件、将固件烧录到设备，或检查项目状态，这些步骤依然需要手动完成。

ESP-IDF Tools 本地 MCP Server 正是为了解决这一问题。它是一个基于 stdio 的 MCP Server，内置于 idf.py 中，可向任何支持 MCP 的 AI 客户端暴露项目操作与项目状态。你无需再将聊天窗口中的命令复制到终端，而是可以直接告诉 AI 助手：将目标设置为 ESP32-C6、构建项目、列出已连接设备并执行烧录 —— 它会直接完成这些步骤。

两类 Server 结合后，便形成了完整的 AI 辅助开发工作流：Documentation Server 提供知识，Tools Server 提供执行能力。

	Documentation MCP Server	Tools 本地 MCP Server
传输方式	远程（HTTP/SSE）	本地（stdio）
功能	获取 Espressif 文档	执行项目操作（构建、烧录等）
是否需要安装 ESP-IDF	否	是（v6.0+，通过 EIM）
身份认证	GitHub / 微信登录	无（本地运行）

可用的 Tools 与 Resources

Tools MCP Server 提供两类能力：Tools（AI 可执行的操作）与 Resources（只读项目数据）。

Tools

Tool	描述
`set_target(target)`	设置芯片目标（esp32、esp32s3、esp32c6 等）
`build_project()`	构建 ESP-IDF 项目
`flash_project(port)`	将已构建的固件烧录至已连接设备
`clean_project()`	删除构建产物

Resources

Resource	描述
`project://config`	当前项目配置及构建目录信息
`project://status`	构建状态、当前目标芯片、IDF 版本以及构建产物情况
`project://devices`	已连接串口列表

这些 Tools 与熟悉的 idf.py 子命令一一对应，因此 AI 实际上执行的就是你平时手动运行的同类操作。而 Resources 则为 AI 提供了足够上下文，使其能够回答诸如"项目是否已经构建完成？"或"当前有哪些可用串口？"等问题，而无需你手动检查。

环境准备

开始前，请确保环境满足以下要求：

获取 EIM 安装器 v0.8.1 或更新版本
通过 EIM 安装 ESP-IDF v6.0 或更新版本
在安装 ESP-IDF 时启用 mcp 功能 —— 关于如何启用特定功能，请参见 EIM CLI Configuration - Global Features
使用支持 MCP 的 AI 客户端，例如 Cursor IDE 或 Claude Code

启动 Server

Tools MCP Server 是一个本地 stdio Server。MCP 定义了两种传输类型：

基于 HTTP 的 Server：运行于远程环境，AI 客户端通过网络与其通信
基于 stdio 的 Server：作为本地进程运行，并通过标准输入/输出（stdin/stdout）与 AI 客户端通信

Tools MCP Server 使用的是 stdio 传输方式 —— AI 客户端会将其作为子进程启动，并直接与其交换消息，无需远程服务或身份认证。

根据你的环境，可通过以下两种方式启动：

方式 1：使用 eim run（推荐）

eim run "idf.py mcp-server"

EIM 会在已激活 ESP-IDF 环境的情况下启动新进程。对于 Cursor IDE 等不会继承 Shell 环境变量的 AI 客户端，这是最佳选择。

方式 2：直接使用 idf.py

idf.py mcp-server

请在已激活 ESP-IDF 环境的 Shell 中运行（例如执行 . ./export.sh 后）。

idf.py -C /path/to/your/project mcp-server

注意：无论使用哪种方式，Server 都必须从有效的 ESP-IDF 项目目录启动，或显式指向该目录。

配置 Tools MCP Server

Tools MCP Server 的配置方式与其他 MCP 集成类似：在 AI 客户端中注册 Server，打开 ESP-IDF 项目，然后即可开始使用 AI 助手。

以下示例以 Cursor IDE 与 Claude Code 为例，但相同方法同样适用于任何支持 MCP 的 AI 客户端 —— 请参考对应客户端文档，了解如何注册本地 stdio MCP Server。

Cursor

第一步：在电脑上打开 Cursor，并打开你的 ESP-IDF 项目。

第二步：打开 Cursor Settings，进入 Tools & MCP 标签页，点击 “Add custom MCP server” 按钮。
在这里插入图片描述

第三步：将以下内容添加到 .cursor/mcp.json 文件中：

{
  "mcpServers": {
    "esp-idf-eim": {
      "command": "eim",
      "args": [
        "run",
        "idf.py mcp-server"
      ],
      "env": {
        "IDF_MCP_WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    }
  }
}

IDF_MCP_WORKSPACE_FOLDER 变量用于告诉 Server 哪个目录是你的 ESP-IDF 项目。这是必要的，因为 Cursor 的 AI 进程不会继承你的 Shell 环境，因此 Server 无法自行发现项目目录。

第四步：返回 Settings > Tools & MCP 页面，找到 esp-idf-eim 条目。当 Server 成功启动后，它会显示绿色状态指示灯。如果显示错误，请参考下方的故障排查章节。
在这里插入图片描述

第五步：打开 AI Chat（Agent 模式），并尝试如下提示词：

Set the target to esp32s3 and build the project.

注意：部分 AI Agent 可能不会自动使用 MCP Server。如果出现这种情况，请在提示词中显式说明，例如：
Set the target to esp32s3 and build the project. - Use MCP server.

AI 助手会尝试通过 MCP Server 调用 set_target 和 build_project，并向你请求执行权限。
在这里插入图片描述
一次成功执行后的典型返回结果如下：

Here is what ran via the ESP-IDF MCP server:

set_target — target: esp32s3
Result: Target set to: esp32s3

build_project — no extra arguments
Result: Successfully built project

The project is configured for ESP32-S3 and the build completed successfully
through MCP. If you want a follow-up (e.g. flash_project or project://status),
say what you need next.

Claude Code

第一步：使用 Claude CLI 注册 Server：

claude mcp add --transport stdio esp-idf-eim -- eim run "idf.py mcp-server"

你可以通过运行 claude mcp list 来验证连接状态。
在这里插入图片描述
第二步：进入你的 ESP-IDF 项目目录，并启动 Claude Code：

claude

尝试如下提示词：

Show me the project status and list connected serial devices.

注意：部分 AI Agent 可能不会自动使用 MCP Server。如果出现这种情况，请在提示词中显式说明：
Show me the project status and list connected serial devices. Use the MCP server.

AI 助手会通过 MCP Server 读取 project://status 与 project://devices。典型返回结果如下：

ESP-IDF Project: hello_world
- Target: esp32s3
- IDF Version: v6.0
- Project Path: /home/user/esp/projects/hello_world
- Build Directory: /home/user/esp/projects/hello_world/build

Build Artifacts:
- ✓ Bootloader: Built
- ✓ Partition table: Built
- ✗ Application flash: Not built
- ✓ Flash arguments: Generated

Connected Serial Devices
Available ports:
- /dev/cu.debug-console
- /dev/cu.Bluetooth-Incoming-Port (Bluetooth)

Note: No ESP32 serial devices are currently connected. The available
ports are system console and Bluetooth devices. To flash the project,
you'll need to connect an ESP32-S3 device via USB.

如果你同时使用 Documentation MCP Server，也可以在同一配置中注册两个 Server。例如，在 Cursor 的 .cursor/mcp.json 中：

{
  "mcpServers": {
    "esp-idf-eim": {
      "command": "eim",
      "args": [
        "run",
        "idf.py mcp-server"
      ],
      "env": {
        "IDF_MCP_WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    },
    "espressif-docs": {
      "url": "https://mcp.espressif.com/docs"
    }
  }
}

VS Code

注意：VS Code 同时支持全局（用户级）与本地（项目级）MCP Server 配置。对于当前场景，请使用本地配置 —— VS Code 无法在全局 MCP 配置中稳定解析 ${workspaceFolder}。这意味着你需要在每个希望使用 MCP Server 的 ESP-IDF 项目中创建 .vscode/mcp.json 文件；而 Cursor 或 Claude Code 则只需一次全局注册即可覆盖所有项目。

第一步：在 VS Code 中打开 ESP-IDF 项目（File > Open Folder…）

第二步：在项目根目录创建 .vscode/mcp.json，添加如下配置：

{
  "servers": {
    "esp-idf-eim": {
      "command": "eim",
      "args": [
        "run",
        "idf.py mcp-server"
      ],
      "env": {
        "IDF_MCP_WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    }
  }
}

IDF_MCP_WORKSPACE_FOLDER 变量用于告诉 Server 哪个目录是你的 ESP-IDF 项目。这是必要的，因为 VS Code 的 AI 进程不会继承 Shell 环境，因此 Server 无法自行发现项目目录。

第三步：稍等片刻后，会出现一个 Start 按钮，点击即可启动 MCP Server。
在这里插入图片描述
第四步：确认 Server 已成功运行 —— Server 名称旁应显示 ✓。

注意：默认情况下，VS Code 的 AI Chat 仅暴露 MCP Tools（例如 build、flash 等操作）。MCP Resources（project://status、project://config、project://devices）不会自动附加到对话上下文中。如需在对话中包含某个 Resource，请点击聊天输入框中的 + 按钮，在上下文菜单中选择 MCP Resources…，然后选取所需资源。

在这里插入图片描述

第五步：打开 AI Chat，尝试如下提示词：

Set the target to esp32s3 and build the project.

注意：部分 AI Agent 可能不会自动调用 MCP Server。如果出现这种情况，请在提示词中显式说明：Set the target to esp32s3 and build the project. Use the MCP server.

AI 助手会通过 MCP Server 调用 set_target("esp32s3") 与 build_project()。VS Code 会在执行每次 Tool 调用前请求你的确认。
在这里插入图片描述
确认后，典型返回结果如下：

Target was set to esp32s3 via MCP, and the project build completed successfully via MCP as well.

如果你同时使用 Documentation MCP Server，也可以在同一配置中注册两个 Server。在 .vscode/mcp.json 中添加：

{
  "mcpServers": {
    "esp-idf-eim": {
      "command": "eim",
      "args": [
        "run",
        "idf.py mcp-server"
      ],
      "env": {
        "IDF_MCP_WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    },
    "espressif-docs": {
      "url": "https://mcp.espressif.com/docs"
    }
  }
}

示例工作流

以下是一个真实的多步骤会话示例，展示 Tools MCP Server 在实际中的工作方式。

Step 1 – 配置并构建

Set the target to esp32c6 and build the project.

AI 助手会先调用 set_target("esp32c6")，随后调用 build_project()。构建进度与最终结果（成功或错误输出）都会返回给用户。

Step 2 – 检查设备并烧录

Show me connected devices and flash the firmware.

AI 助手会读取 project://devices 来发现可用串口，然后调用 flash_project(port) 并指定对应端口。

Step 3 – 验证结果

What is the current build status?

AI 助手会读取 project://status 与 project://config，并返回目标芯片、IDF 版本、项目路径以及当前存在的构建产物信息。

Step 4 – 清理构建产物

Clean the build artifacts.

AI 助手会调用 clean_project() 删除构建目录内容。

上述每一步都通过受控接口执行，并真实反映当前项目状态。AI 助手并非"猜测"或"模拟"操作 —— 它执行的是真实的 idf.py 命令，并返回真实输出结果。

同时使用两个 MCP Server

Documentation MCP Server 与 Tools MCP Server 被设计为互补关系：

Documentation Server 为 AI 提供数据手册、API Reference、迁移指南以及硬件设计指南等文档能力
Tools Server 让 AI 能够基于这些知识执行项目构建、烧录与管理操作

当两个 Server 同时配置后，AI 便可以处理跨越"文档查询 + 项目操作"的完整任务。例如：

Check the ESP-IDF documentation for the recommended I2C pins on ESP32-C3,
update the pin configuration in my project, and build it.

在这一场景中，AI 助手会先通过 Documentation MCP Server 查询硬件参考信息，随后修改源代码，再通过 Tools MCP Server 构建项目并验证结果。

关于 Documentation MCP Server 的配置说明，请参见配套文章。

故障排查

“MCP dependencies not available”

当前 ESP-IDF 环境未安装 mcp 功能。请重新运行 EIM 安装器，并确保启用了 mcp 功能。详细信息请参考 EIM 文档。

“Open the MCP server in a valid ESP-IDF project directory”

Server 未能找到有效的 ESP-IDF 项目。请确认：

Server 是从项目目录内启动的
或 IDF_MCP_WORKSPACE_FOLDER 已正确指向项目目录

有效项目目录需包含引用 ESP-IDF Project CMake 文件的 CMakeLists.txt。

Cursor 中未显示 Server

请在终端中运行 eim --version，确认 eim 已加入系统 PATH。

如果 Cursor 无法找到 eim，Server 将静默启动失败。同时请确认 .cursor/mcp.json 文件存在且 JSON 格式合法。

总结

ESP-IDF Tools 本地 MCP Server 为 AI 助手提供了一种直接、结构化的方式来操作 ESP-IDF 项目。其核心价值非常直接：AI 助手不仅能够描述操作流程，还能真正执行项目操作 —— 包括设置目标芯片、构建、烧录、清理以及查询状态。

结合 Documentation MCP Server 后，它进一步形成了完整的 AI 辅助开发闭环：查询正确的 API 或配置、修改代码、构建并烧录 —— 全部都可在一次对话中完成。

如果你已经在使用支持 MCP 的 AI 客户端，那么这一功能能够让 AI 辅助在日常 ESP-IDF 开发中变得更加实用。只需将 MCP Server 添加到 AI 客户端配置中，将其连接到项目，然后即可通过自然语言驱动熟悉的 set_target → build → flash 工作流。

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

* AI路由工作流智能体

AtomGit开源社区

掌握RAG核心技术：从玩具走向产品的关键升级！

AtomGit开源社区

Qwen3.5微调全攻略：SFT、RLHF、多模态到Agent，20+模板+实战代码，速成大模型高手！

AtomGit开源社区

所有评论(0)

查看更多评论

乐鑫科技 Espressif

@espressif

已为社区贡献8条内容

ESP-IDF Tools 本地 MCP Server：通过 AI 助手构建、烧录与管理项目

乐鑫科技 Espressif

背景

可用的 Tools 与 Resources

Tools

Resources

环境准备

启动 Server

方式 1：使用 eim run（推荐）

方式 2：直接使用 idf.py

配置 Tools MCP Server

Cursor

Claude Code

VS Code

示例工作流

Step 1 – 配置并构建

Step 2 – 检查设备并烧录

Step 3 – 验证结果

Step 4 – 清理构建产物

同时使用两个 MCP Server

故障排查

“MCP dependencies not available”

“Open the MCP server in a valid ESP-IDF project directory”

Cursor 中未显示 Server

总结

所有评论(0)

温馨提示：您尚未绑定手机号

乐鑫科技 Espressif