ESP32 Simulator MCP server

esp32sim-mcp

Your agent writes ESP32 firmware, boots it and tests it. No board, no account.

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

npx -y esp32sim-mcp setup                      # emulator + mask ROMs, pinned and SHA-256 verified
cd 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.

What the agent sees

From a real session, the agent calls:

{
  "tool": "sim_expect",
  "projectDir": ".",
  "chip": "s3",
  "board": "none",
  "maxSeconds": 10,
  "patterns": ["Hello world!", "Counter: 1", "Counter: 2", "Counter: 3", "Counter: 4", "Counter: 5"]
}

and gets back:

### Expect Test: ✅ PASSED

Matched 6 / 6 patterns.

- ✅ Matched (line 54): `Hello world!`
- ✅ Matched (line 55): `Counter: 1`
  ...
- ✅ Matched (line 65): `Counter: 5`

#### Full UART Logs:
ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
rst:0x1 (POWERON),boot:0xf (SPI_FAST_FLASH_BOOT)
...

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

Shortened. The full README is on GitHub.