# ESP32 Simulator

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 8 repo stars
- Author: stramanu
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/stramanu/esp32sim-mcp
- Updated: 2026-10-19
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/esp32-simulator

## What it 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).

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add esp32sim-mcp -- npx -y esp32sim-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add esp32-simulator -- npx -y esp32sim-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "esp32-simulator": {
            "command": "npx",
            "args": [
                "-y",
                "esp32sim-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "esp32-simulator": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "esp32sim-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add esp32-simulator npx -y esp32sim-mcp
```

## When to use it
- 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
- 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`.

## Similar
- [esp32-wroom-38pin](https://affpapa.org/en/nevibecode/skills/esp32-wroom-38pin.md) — skill · ★ 29 repo stars
- [esp32-wroom-36pin](https://affpapa.org/en/nevibecode/skills/esp32-wroom-36pin.md) — skill · ★ 29 repo stars
- [esp32-firmware-engineer](https://affpapa.org/en/nevibecode/skills/esp32-firmware-engineer.md) — skill · 1500 installs
- [esp32-ai-agent-skill](https://affpapa.org/en/nevibecode/plugins/esp32-ai-agent-skill.md) — plugin · ★ 59 repo stars
- [ota-deployment-guardian](https://affpapa.org/en/nevibecode/skills/ota-deployment-guardian.md) — skill · 115 installs
- [flashduck-dev](https://affpapa.org/en/nevibecode/skills/flashduck-dev.md) — skill · ★ 187 repo stars

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
