Metadata-Version: 2.4
Name: esp-idf-mcp
Version: 1.1.0
Summary: MCP server that lets AI agents build, flash, and monitor ESP-IDF projects on real hardware
Author: Maty403
License: MIT
Keywords: esp-idf,esp32,mcp,model-context-protocol,esptool,ai-agent,embedded
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyserial>=3.5
Dynamic: license-file

# esp-idf-mcp

![License](https://img.shields.io/badge/license-MIT-green) ![Platform](https://img.shields.io/badge/platform-Windows-blue) ![Python](https://img.shields.io/badge/python-3.9%2B-blue) ![Protocol](https://img.shields.io/badge/protocol-Model%20Context%20Protocol-purple)

A [Model Context Protocol](https://modelcontextprotocol.io) (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.

<!-- mcp-name: io.github.Maty403/esp-idf-mcp -->

## 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:

   ```powershell
   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:

   ```powershell
   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 .`:

   ```toml
   [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](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-py.html#esp-idf-mcp-server) (documentation checked 2026-10-26):

| Workflow | Built-in ESP-IDF Tools MCP | esp-idf-mcp |
| --- | --- | --- |
| Set target, build, flash, clean | Yes | Yes |
| Create a project | Sample template | Minimal template or bundled ESP-IDF example |
| Monitor a device | Wait for expected output; full serial log is saved | Persistent read/send/close sessions, incremental and full-log views, baud-rate detection, and USB reconnect handling |
| Project and device context | Project config, build status, connected-device resources | Connected-device resource plus chip model, revision, crystal, MAC, and flash details |
| Components and hardware tests | Not listed in the built-in Tools MCP tool set | Browse bundled examples, add/remove component dependencies, and run `pytest-embedded` hardware tests |

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 | Purpose |
| --- | --- |
| `build_project` | `idf.py build` (same as a manual build, no configuration rewriting) |
| `flash_project` | esptool flash; when `port` is omitted it is auto-detected (only if exactly one non-COM1 port is connected — otherwise the call refuses and lists the candidates); closes only that port's monitor session before flashing, then opens a persistent monitor session on it (baud from `sdkconfig`) for `monitor_read` |
| `read_chip_info` | Chip model, revision, features, crystal, MAC, flash vendor/device/size |
| `set_target` | `idf.py set-target` (esp32, esp32s3, esp32c2, …) |
| `create_project` / `list_examples` | Create a new project (minimal template or a bundled official example); browse the examples shipped with the installed IDF |
| `add_dependency` / `remove_dependency` | Manage ESP component manager dependencies in `idf_component.yml` |
| `clean_project` | Incremental clean or fullclean |
| `monitor_open` / `monitor_read` / `monitor_send` / `monitor_close` | Persistent interactive serial session; `monitor_read` starts at `Returned from app_main()` (everything before folded into a count), collapses adjacent duplicates as `<first line>  *N`, offers `full=True` for a cursor-independent dump of everything retained, `timestamp=True` to keep the ms prefix, and writes every line to `<project>/.esp_monitor_full.log`; `monitor_close(session_id)` (or a bare port name) releases exactly that session / port; a session auto-releases after `idle_release` seconds (default 120) without read/write |
| `run_pytest` | Run `pytest-embedded` hardware tests |
| `project://devices` (resource) | List connected serial ports |

### 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](https://docs.espressif.com/projects/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

```bash
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

```json
{
  "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:

| Env var | Meaning |
| --- | --- |
| `IDF_PATH` | ESP-IDF framework root (overrides auto-detection) |
| `IDF_PYTHON_ENV_PATH` | ESP-IDF Python virtualenv (default: newest under `<tools>\python\*\venv`) |
| `IDF_TOOLS_PATH` | Espressif tools directory (default: `C:\Espressif\tools`, then `D:\espressif\tools`) |
| `ESP_IDF_VERSION` | Version label — derived from the IDF directory name with the leading `v` stripped (`v6.1` → `6.1`), so the component manager can parse it |
| `IDF_COMPONENT_MANAGER` | Forced to `1` so `idf.py add-dependency` and managed components resolve |

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 |
| :---: | :---: |
| <img src=".github/assets/reward_alipay.jpg" width="220"> | <img src=".github/assets/reward_binance_pay.png" width="220"> |
| [Scan to pay](https://qr.alipay.com/tsx16565gbtfpahg1korif1) | [Scan in the Binance app](https://app.binance.com/uni-qr/JmgBCLce) |

| USDT (TRC-20) | USDT (BEP-20 / BSC) |
| :---: | :---: |
| <img src=".github/assets/reward_usdt_trc20.png" width="220"> | <img src=".github/assets/reward_usdt.png" width="220"> |
| Scan, or copy the address:<br>`TL4j1mRbfjQBEGpqBbRTEYHvJABxCi3tkQ` | Scan, or copy the address:<br>`0x1572a9a6ce3da8b55c6cfc67e5b0557f3f10d423` |

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

## License

[MIT](LICENSE)
