Boot and test ESP32 firmware in a local emulator: UART asserts, buttons, virtual WiFi, screenshots.
ESP32Sim MCP Server (io.github.stramanu/esp32sim-mcp)
This MCP server provides tooling to boot and test ESP32 firmware in a local emulator. It supports UART output assertions, button interactions, virtual WiFi, and capturing emulator screenshots. The focus is on running firmware tests without deploying to physical ESP32 hardware.
๐ ๏ธ Key Features
Local emulator for ESP32 firmware
UART asserts during testing
Button support in the emulator
Virtual WiFi simulation
Screenshot capture for test evidence
๐ Use Cases
Validate ESP32 firmware behavior via UART assertions
Exercise firmware logic that depends on button inputs
Test features requiring network behavior using virtual WiFi
Collect visual output via emulator screenshots
โก Developer Benefits
Repeatable local testing workflow for ESP32 firmware
Observable results through UART assertions and screenshots
โ ๏ธ Limitations
Limited to emulator-based testing for ESP32 firmware (no physical device execution described)
Your agent writes ESP32 firmware, boots it and tests it. No board, no account.
Claude Code adds a counter to an ESP-IDF project, builds it and verifies it in the emulator
A real Claude Code session, recorded live (only the idle tail is trimmed): it edits ESP-IDF's hello_world, builds it in Docker because ESP-IDF isn't installed, and checks the console in the emulator.
Coding agents are good at writing embedded C. They are blind when it comes to running it: without a board on the desk, "it compiles" is where the feedback loop ends.
esp32sim-mcp closes that loop. It gives Claude Code, Codex, Cursor or any MCP client a set of tools that boot the firmware the agent just built inside esp32sim, a local instruction-level ESP32 emulator, and hand back what the chip printed, whether it crashed, and what was on the display. The agent reads the result, fixes the code and tries again, the way you would with a board on the bench.
๐ No hardware, no cloud. Everything runs on your machine. No account, no token, no board.
๐งฌ Real boot chain. Espressif's mask ROM, the ESP-IDF bootloader and your unmodified app, on ESP32-S3, C3, C6 and the classic ESP32.
๐ก More than a console. Virtual WiFi access point with DHCP, DNS and NAT, buttons, rotary encoder, GPIO, UART input, touch, and display screenshots.
๐งช Assertions, not vibes.sim_expect returns pass/fail and the exact line that is missing, so the agent knows what to fix.
โก Fast. Emulation usually runs ahead of real time: on Apple silicon, 8 emulated seconds of a WiFi station joining a network take about 0.6 s.
๐ค Comes with a skill.init installs an agent skill that teaches the write โ build โ simulate โ fix loop, including building in Docker when ESP-IDF is not installed.
Quickstart
bash
npx -y esp32sim-mcp setup # emulator + mask ROMs, pinned and SHA-256 verifiedcd your-esp-idf-project
npx -y esp32sim-mcp init # registers the MCP server and the skill for your agents
Then ask your agent for something you can see on the serial console:
Add a counter that prints once a second, build it, and check in the simulator that it reaches 5.
Requirements: Node.js 22+, and ESP-IDF or Docker to build firmware. Prebuilt emulator binaries cover macOS (Apple silicon) and Linux (x64, arm64); see other platforms.
When something goes wrong, it gets the panic instead (Guru Meditation Error, stack overflow, failed assert, heap corruption) with the log leading up to it, and the missing pattern spelled out.
Tools
Tool
What it does
sim_run
Boots the firmware and returns the console log, stop reason, emulated time and any panic.
sim_expect
Runs the firmware and asserts that strings or regexes appear on the console, in order by default.
sim_script
Drives the hardware at emulated timestamps: press/release buttons, gpio levels, knob turns, uart/serial input, touch, stop.
sim_screenshot
Returns a PNG of the board's display at a given emulated time.
sim_list_boards
Lists chips, boards, displays and inputs.
sim_doctor
Checks the emulator and ROMs and says how to fix what is missing.
All tools take a projectDir (the ESP-IDF build is found through build/flasher_args.json) or explicit appBin/bootloaderBin/ptableBin paths, plus chip, board and wifi (e.g. ssid=demo,psk=secret). Both UART0 and the USB-Serial/JTAG console are captured, so output shows up whichever one the project logs to.
How it works
flowchart LR
A["Coding agent<br/>(Claude Code, Codex, Cursor)"] -- "edits code,<br/>runs idf.py build<br/>(local or Docker)" --> B["ESP-IDF build/"]
A -- "MCP: sim_expect, sim_run, ..." --> C["esp32sim-mcp"]
C -- "flasher_args.json" --> B
C -- "spawns" --> D["esp32sim emulator<br/>mask ROM โ bootloader โ app"]
D -- "UART / USB-JTAG, panics,<br/>display, virtual WiFi" --> C
C -- "pass/fail, logs, PNG" --> A
esp32sim-mcp is a thin, tested layer: it finds the build, translates tool calls into esp32sim's command line, separates and de-duplicates the two consoles, detects panics, and shapes the result for an agent. The emulation itself is esp32sim's work.
Use it in CI
The same checks run without an agent, with exit code 0 on pass and 1 on fail. A GitHub Actions job that builds your firmware and asserts its boot log:
setup installs prebuilt binaries on macOS arm64 and Linux x64/arm64. They are built from source by this repository's emulator workflow with signed build provenance (gh attestation verify <archive> -R stramanu/esp32sim-mcp). Elsewhere, build esp32sim with Cargo (rustup), pinned to the commit this release is tested against:
ESP32SIM_PATH points at an emulator binary elsewhere and ESP32SIM_ROM_DIR at another ROM directory; ROMs inside an ESP-IDF install are found automatically.
esparagus is the natural next step: simulate first with esp32sim-mcp, then confirm on a real board.
Limitations
An emulator is not silicon. Peripherals esp32sim does not model, RF timing and Bluetooth are out of reach here; confirm on hardware before you ship.
The agent builds the firmware itself (idf.py, locally or in Docker); the MCP server does not compile.
Windows is untested.
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for the development setup and how the end-to-end tests run against the real emulator, and CHANGELOG.md for what changed.
Credits
esp32sim by Joakim Eriksson, Alice and Mattia Fiumara: the emulator that does the real work (MIT).
Espressif: ESP-IDF and the mask ROM ELFs (Apache-2.0).