ESP-IDF MCP

esp-idf-mcp

A Model Context Protocol (MCP) server that lets AI agents build, flash, and monitor ESP-IDF projects on real hardware — end to end, from source code to boot logs.

Instead of an agent only being able to *write* firmware code, this server closes the loop: compile → flash over serial → capture boot logs → run pytest-embedded hardware tests — all without leaving the agent's tool set.

Quick start (Windows + Codex)

Requirements: ESP-IDF, Python 3.9 or newer, and an MCP-capable Codex client. A connected board is needed only for flashing, serial monitoring, and hardware-in-the-loop tests.

1. Clone this repository and install it into the Python environment Codex will use:

   git clone https://github.com/Maty403/esp-idf-mcp.git

cd esp-idf-mcp python -m pip install .

1. Add the server to Codex. The desktop app, CLI, and IDE extension share the MCP configuration. From a terminal, run:

   codex mcp add esp-idf -- esp-idf-mcp

codex mcp list

If esp-idf-mcp is not on your PATH, open %USERPROFILE%\.codex\config.toml and add the following, replacing both paths. Use the same Python environment where you ran pip install .:

   [mcp_servers.esp-idf]

command = "C:\\path\\to\\python.exe" args = ["C:\\path\\to\\esp-idf-mcp\\esp_idf_mcp.py"]

1. Restart Codex, open an ESP-IDF project, and ask: “Build this ESP-IDF project.” In the desktop app, check Settings → MCP servers or type /mcp to confirm the server is connected.

Demo workflow

With an ESP-IDF project open and a board connected, try:

1. “Read the connected chip info and list the serial devices.”
2. “Build this project.”
3. “Flash this project to COM3, then monitor the boot log and summarize the application output.”

Replace COM3 with the correct port shown on your machine. Confirm the target board and port before flashing.

Where this server fits

A community-built local MCP server for ESP-IDF hardware workflows. Use it to let an AI agent build firmware, interact with serial-connected boards, and run hardware-in-the-loop tests from the same workflow.

Feature comparison

Compared with Espressif's built-in ESP-IDF Tools MCP server (documentation checked 2026-10-26):

This table compares the local Tools MCP server with this project. Espressif's separate Documentation MCP and Component Registry MCP servers provide documentation and component discovery; they can complement either local tools server.

Features

• Zero-config ESP-IDF discovery — IDF root, tools directory and the Python venv are located automatically (env var first, else the newest install under D:\esp, C:\esp or ~/esp); toolchain paths are matched by version glob, so upgrading ESP-IDF or a toolchain never requires editing the script.
• Builds through `idf.py build` — the exact same path as a manual build, with no extra configuration rewriting. sdkconfig and sdkconfig.defaults therefore keep their official upstream semantics: the defaults files seed a fresh sdkconfig (the generic sdkconfig.defaults, plus sdkconfig.defaults. when the generic one exists), while values already present in sdkconfig win on later builds. Hand edits in sdkconfig are picked up through the official ninja RERUN_CMAKE flow.
• Flash + auto-monitor in one call — flashes with esptool (reads build/flash_args), waits out the hard-reset boot, then opens a persistent monitor session on that port (the board is reset, so the session only holds the fresh boot log) and returns immediately — poll it with monitor_read. The target port is the one you pass in (when omitted it is auto-detected, but only if exactly one non-COM1 port is connected — otherwise the call refuses and lists the candidates), and only that port's monitor session is closed before flashing (skipped when none is open) — other boards are never disturbed.
• Chip info from real hardware — read_chip_info reports chip model, revision, features, crystal, MAC address, and flash vendor/device/size via esptool, then hard-resets the board back into the running app.
• Baud auto-detected — every serial capture reads CONFIG_ESP_CONSOLE_UART_BAUDRATE from the project sdkconfig (no hardcoded default), so logs are never garbled.
• Session-based serial monitor — monitor_open / monitor_read / monitor_send / monitor_close: a persistent, non-blocking session you poll for *new* lines only. monitor_close(session_id) releases exactly the session — or every session on a given port — that you name. flash_project opens one automatically after every flash, so the boot log is always ready to poll. Sessions free themselves: after idle_release seconds (default 30, per-call override) without a read/write the port is released, so an abandoned session can never hold the COM port hostage.
• Application-layer log view — monitor_read starts its output at the runtime marker main_task: Returned from app_main(): everything before it (boot ROM/bootloader/component logs *plus* your app_main() initialization output) is folded into a count (N lines folded before app start in the header), and the marker plus all following lines (your tasks, wifi, mqtt, plain printf) are printed one per line. An increment carrying no marker is printed as-is when it is a plain continuation, and folded away when it is still inside the boot phase.
• `full` escape hatch + persistent full log — monitor_read(full=True) dumps everything retained in the buffer verbatim (no layer split, no folding, timestamps untouched) without consuming the incremental cursor — the two read modes never interfere. On top of that, every serial line is flushed to a session log file ( /.esp_monitor_full.log), so history survives buffer eviction, USB re-enumeration, board resets and session close. Reading is never lossy — whatever is folded is always counted in the header, and anything evicted lives in the file.
• Agent-friendly output — strips ANSI color escapes at the source, collapses adjacent duplicates into *N so the repeated content stays visible right next to its count (compared with the leading I (12345) prefix ignored, so lines logged at different milliseconds still collapse), keeps only the relevant tail of long output, and reports evicted/skipped counts in the header instead of silently dropping lines.
• Survives USB re-enumeration — after a reset the port can disappear and come back (ESP32-S2/USB-OTG); the read loop reconnects for up to 5 s and clears stale buffered logs; if the port stays lost the session releases itself so monitor_open can re-acquire it.
• Hardware-in-the-loop tests — runs pytest-embedded suites against the real board.

Includes a Windows usbser.sys workaround (RTS-only control transfers need a DTR re-assert) so reset works on USB-CDC ports as well as CH340-style adapters.

Tools

Tool reference

The description each tool exposes to the agent, in full:

`build_project(project_dir, timeout=600)` — Build ESP-IDF project via idf.py build (same as manual). timeout caps the whole build in seconds (default 600); on timeout the process tree is killed and a failure result with extracted error lines is returned. Every call answers with an explicit ✅/❌ verdict. The full output always lands in /.esp_build.log, rewritten every run. Configuration is untouched: sdkconfig.defaults seeds a fresh sdkconfig, values already in sdkconfig win.

`flash_project(project_dir, port=None, monitor=True, wait_after_flash=2.0, timeout=600)` — Flash the built project using esptool directly (reads build/flash_args). Monitor sessions on the target port are closed automatically before flashing — no manual monitor_close needed. When port is omitted it is auto-detected, but only if exactly one non-COM1 port is connected; with several ports connected the call refuses and lists them, so a flash can never land on the wrong board. monitor=True opens a persistent session afterwards (baud read from sdkconfig); wait_after_flash lets the hard-reset boot finish before the monitor opens, so the session holds a clean boot log. timeout caps the whole flash in seconds (default 600). The full output always lands in /.esp_flash.log, rewritten every run.

`create_project(path, example='')` — Create a new ESP-IDF project at the absolute path (must not exist or be empty). With example set (e.g. 'get-started/hello_world'), the project is copied from an official example bundled with the installed IDF — browse them with list_examples; the root project() name is renamed to the new directory when found. Without example, a minimal template project is created via idf.py create-project. Both fully offline; to pull registry components into the new project, call add_dependency afterwards (downloaded on the next build).

`list_examples(category='')` — List official ESP-IDF examples bundled with the installed IDF. Without arguments, lis