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 .
   

2. 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"]
   

3. 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.<target> 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 (<project>/.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 <first line> *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 10 s and clears stale buffered logs.
• 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 <project_dir>/.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 <project_dir>/.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, lists the categories (get-started, wifi, peripherals, …); with a category, lists the examples inside it as paths ready for create_project(example=…).

read_chip_info(port=None, baud=115200) — Chip model, revision, features, crystal frequency, MAC address and flash vendor/device/size via esptool. The board is briefly put into download mode and hard-reset back into the running app afterwards. PSRAM details are not available here — read the boot log with monitor_open instead.

monitor_open(port, reset=True, project_dir=None, idle_release=120, baud=0) — Open a persistent serial monitor session and return immediately (non-blocking). reset=True hard-resets the board after clearing the buffers, so the session starts from a fresh boot. A baud > 0 is used as-is and skips auto-detection; with the default baud=0 the rate is auto-detected from project_dir's sdkconfig (CONFIG_ESP_CONSOLE_UART_BAUDRATE, fallback 115200). project_dir also starts the session full log at <project_dir>/.esp_monitor_full.log (rewritten from scratch at every session open; within a session every line is flushed as it arrives, so history survives buffer eviction, re-connects and board resets; without a project dir the session keeps no full-log file). The session id is PORT@BAUD (e.g. COM17@115200). idle_release sets the session lifetime in seconds of no monitor_read/monitor_send (default 120): past it the session stops itself and frees the port, so a session abandoned by the client (MCP clients tend to leave server processes alive without closing the stdio pipes) cannot hold the COM port — including across USB unplug/replug, since the read loop would otherwise re-grab the port. Any monitor_read/monitor_send resets the timer; pass a larger value to bridge a long pause, or monitor_close explicitly when done. If a call reports No session, just monitor_open again — the full history is in the log file.

monitor_read(session_id, full=False, timestamp=False, max_lines=0, match='') — Read the lines that arrived since the last read. Output starts at the runtime marker main_task: Returned from app_main(): everything before it (boot logs and app_main() initialization chatter) is folded into a count, reported as N lines folded before app start, and the marker plus every following line is printed one per line. Adjacent duplicates collapse into <first line> *N, so the repeated content always stays visible next to its count (comparison ignores the leading I (12345) prefix, so lines logged at different milliseconds still collapse). An increment with no marker is printed as-is when it is a plain continuation, and folded away when it is still inside the boot phase. full=True switches to a cursor-independent full dump: it emits every line retained in the ring buffer verbatim (no folding, no layer split, timestamps untouched) and does not advance the incremental cursor, so the folded and full views never interfere; max_lines caps the returned tail (0 = everything retained). The header reports M evicted by buffer cap and K older skipped (showing last T) when applicable, plus the full log file path — lines evicted from the ring are never lost, they are in the file. timestamp=True keeps the ms prefix (default strips it to TAG: msg).

match filters the output by regex (case-insensitive, matched against the line text without the level/ms prefix; | separates alternatives, e.g. match='heap|wifi|dhcp'). When it is set, the app-start folding is bypassed and only matching lines are returned — useful to pull one topic out of a noisy log. Lines that matter for diagnostics always pass through even when they match nothing: every ESP_LOG error-level line (E (…)) plus the panic-handler prints that carry no log-level prefix (Guru Meditation / panic'ed, abort() was called, assert failed, Backtrace:, stack canary, watchdog and brownout triggers, CORRUPT HEAP, core dumps, reset reasons, Rebooting…) — a filtered view never hides a crash. Filtered-out lines are still consumed by the incremental cursor; combine match with full=True to re-scan everything retained in the buffer with the same filter.

monitor_send(session_id, data, press_enter=True) — Write text to the device's serial input (shell commands, menu selections); press_enter appends CRLF.

monitor_close(session_id) — Release one session (COM17@115200) or every session on a bare port (COM17). There is no release-all mode.

set_target(project_dir, target) — idf.py set-target for esp32 / esp32s3 / esp32c2 / … Note that idf.py renames the existing sdkconfig to sdkconfig.old and generates a fresh one for the new target.

add_dependency(project_dir, dependency, component=None, path=None) / remove_dependency(project_dir, dependency) — Manage the ESP component-manager manifest idf_component.yml; components are fetched or pruned on the next build.

clean_project(project_dir, full=False) — idf.py clean or fullclean (build artifacts only; sdkconfig is never touched).

run_pytest(project_dir, ...) — Run pytest-embedded hardware tests against the real board (flash + interact + assert on serial output).

Resource project://devices — JSON list of the connected serial ports.

Requirements

• ESP-IDF (developed against v6.1 on Windows; other layouts work as long as the auto-detection or the env vars below find your install)
• Python ≥ 3.9 with mcp and pyserial
• Any MCP client (Claude Desktop, Cursor, VS Code, …)

Setup

Option A — install as a package

pip install .

Option B — run the single file directly

Just point your MCP client at esp_idf_mcp.py with any Python that has mcp + pyserial installed (the ESP-IDF venv works well).

Register with your MCP client

{
  "mcpServers": {
    "esp-idf": {
      "command": "python",
      "args": ["C:\\path\\to\\esp_idf_mcp.py"]
    }
  }
}

(or "command": "esp-idf-mcp" with no args if installed via pip)

Configuration

ESP-IDF is located at startup automatically: environment variable first, then the newest install found under D:\esp\<ver>\esp-idf, C:\esp\<ver>\esp-idf or ~/esp/<ver>/esp-idf. The tools directory falls back to C:\Espressif\tools, then D:\espressif\tools. Every path can be overridden from outside:

Toolchain directories (xtensa/riscv GCC, CMake, Ninja, ccache, idf-exe, esp-rom-elfs) under the tools path are matched by version glob and prepended to PATH. A one-line diagnostic (IDF_PATH=… TOOLS=… PYENV=…) is printed to stderr at startup.

Typical agent workflow

read_chip_info → set_target(esp32s3) → build_project → flash_project(port="COM17")
→ monitor_read(session_id) → iterate on code → run_pytest

Support

If this server saves you flashing-debugging loops, leave a star — or buy the author a coffee:

Alipay	Binance Pay
Scan to pay	Scan in the Binance app

USDT (TRC-20)	USDT (BEP-20 / BSC)
Scan, or copy the address: TL4j1mRbfjQBEGpqBbRTEYHvJABxCi3tkQ	Scan, or copy the address: 0x1572a9a6ce3da8b55c6cfc67e5b0557f3f10d423

USDT: send on BSC / BEP-20 only — scan the address with any EVM wallet, or copy it directly.

License

MIT