Passportsim

What passportsim does

The passportsim MCP server provides an agent-facing interface to PassportSim, an emulator for the FoloToy AI Passport based on the ESP32-C3. It is intended for firmware development and debugging without requiring the physical device. Firmware can be loaded from a merged .bin file, an idf.py build directory, or a .pebundle package.

PassportSim also includes a browser interface and command-line application. The browser version runs locally in the page through WebAssembly, while desktop packages support macOS on Apple silicon and Windows 10 or newer on x64. The project is listed in the 📟 Embedded System category because it emulates device behavior and exposes firmware-level inspection features.

How it works

The emulator executes unmodified ESP-IDF images and presents device-facing behavior through a simulated screen, buttons, audio, and serial console. Its advanced interface exposes run control, event recording, the widget tree, and cards for hardware-related areas such as battery, USB, NFC, Wi-Fi, and Bluetooth.

The passportsim MCP server is started through the packaged executable with the mcp argument. An MCP client launches that process using a command and argument configuration, then sends operations to the running emulator. Agents can combine interaction with observation: for example, boot a firmware build, press a control, wait for a matching console line, inspect the resulting UI tree, and save a screenshot.

Setup and configuration

The quickest setup is the hosted browser version, which requires no installation and accepts firmware through the page. For local use, install a release package with the macOS shell installer or Windows PowerShell installer described in the project documentation. Building from source requires Rust, Bun, and just, or the equivalent Make workflow.

A local MCP client configuration points to the PassportSim executable and passes mcp as its argument:

{
  "mcpServers": {
    "passportsim": {
      "command": "/path/to/passportsim",
      "args": ["mcp"]
    }
  }
}

The repository also provides an optional agent skill that can be installed with npx skills add BlackHole1/passportsim or copied into an agent's skills directory. No environment variables are documented as required for the MCP process.

Tools and capabilities

The passportsim MCP server supports agent workflows that need to:

• Start or boot a firmware build in the emulator.
• Press simulated device buttons.
• Wait for a specified console line.
• Read the serial console.
• Inspect the firmware's UI tree.
• Capture screenshots for visual checks.

The command-line application provides related operations, including starting firmware, reading serial output, taking PNG screenshots, and stopping the emulator. Browser advanced mode additionally supports pausing, stepping, saving and restoring state, and inspecting tasks and memory.

Limitations and notes

Desktop support is documented for macOS on Apple silicon and Windows 10 or newer on x64. Linux is not supported. The browser version is documented for Chrome, Edge, Firefox, and Safari. Browser-loaded firmware remains in the browser and is not uploaded according to the project documentation.

The emulator targets the FoloToy AI Passport environment, so it should be evaluated against the firmware and device behaviors relevant to that platform rather than treated as a general ESP32 emulator. The project is licensed under MIT.