ESP32 Simulator — Claude Code MCP server: install and setup
ESP32 Simulator is an MCP server for Claude Code that runs ESP32 firmware inside a local emulator. It verifies UART output, captures crashes, and simulates hardware peripherals without physical boards.
MIT ★ 8 updated 2026-10-19
claude mcp add esp32sim-mcp -- npx -y esp32sim-mcpWhat ESP32 Simulator does
The server connects your agent to the esp32sim instruction-level emulator. It boots the Espressif mask ROM, the ESP-IDF bootloader, and the user application. Supported chips include classic ESP32, S3, C3, and C6.
The toolset provides sim_run for console logs, sim_expect to assert UART strings, and sim_script to trigger buttons or GPIO levels. It includes virtual Wi-Fi with DHCP and NAT. Display frames export to PNG through sim_screenshot.
Running the server requires Node.js 22 or newer, alongside Docker or a local ESP-IDF setup. Precompiled binaries support macOS on Apple silicon and Linux (x64, arm64).
What it helps with
- run and debug ESP32 firmware without connected hardware
- assert UART output patterns during automated tests
- simulate GPIO signals, button presses, and Wi-Fi connections
- inspect display buffers by saving board screenshots
Example prompts for the agent
- Build the project in Docker and verify in the simulator that Counter: 5 appears in UART logs.
- Run the ESP32-S3 firmware for 5 seconds and take a screenshot of the virtual display.
- Check the build for Guru Meditation panics using
sim_run.
How to install ESP32 Simulator
Platform CLI
claude mcp add esp32sim-mcp -- npx -y esp32sim-mcpPlatform CLI
codex mcp add esp32-simulator -- npx -y esp32sim-mcpConfig file
{
"mcpServers": {
"esp32-simulator": {
"command": "npx",
"args": [
"-y",
"esp32sim-mcp"
]
}
}
}Config file
{
"servers": {
"esp32-simulator": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"esp32sim-mcp"
]
}
}
}Platform CLI
gemini mcp add esp32-simulator npx -y esp32sim-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ESP32 Simulator
How do I install ESP32 Simulator in Claude Code?
Run claude mcp add esp32-simulator -- npx -y esp32sim-mcp.
What does ESP32 Simulator do?
It boots ESP-IDF firmware binaries inside a local emulator, feeding serial output, panic traces, and screen renders back to the agent.
What is required to run ESP32 Simulator?
It requires Node.js 22 or higher, plus either Docker or a local ESP-IDF installation to compile firmware.