ucsim-mcp

A Model Context Protocol (MCP) server for the µCsim microcontroller simulator, built with FastMCP. It lets an AI model (or any MCP client) load firmware images, reset/run/step a simulated CPU, inspect and modify memory and registers, set breakpoints, and drive peripherals on virtual hardware targets — the whole ucsim_* family (ucsim_51/s51, ucsim_z80, ucsim_stm8, …).

How it works

The server is a thin adapter over the pyucsim client library, which does the actual simulator driving: it holds one long-lived ucsim_* process per session, driven over a pseudo-terminal with a unique prompt marker (ucSim only prints its prompt on a TTY).

pyucsim handles several ucSim quirks transparently:

• @ in a filename crashes ucSim (it parses file@memoryspace). Images whose path contains @ — e.g. M2764A@DIP28.HEX — are copied to a safe temp path before loading.

• run N does not stop after N cycles on the MCS-51 build (it free-runs until a breakpoint). Use the step tool for a bounded, deterministic advance.

• Commands are never pipelined after a run/step, which ucSim would otherwise swallow as a user interrupt.

MCP client ──stdio──▶ ucsim-mcp (FastMCP tools) ──▶ pyucsim.UCSimEngine ──pty──▶ ucsim_51

Related MCP server: dbgprobe-mcp-server

Install

The simulator binary is not bundled — point the server at your own ucSim build. (A ucsim_* / s51 binary is auto-discovered on PATH, then a local build at ~/github/razr/ucsim/src/sims/s51.src/ucsim_51.)

This package depends on the pyucsim library. Until both are published, install pyucsim from its sibling checkout first:

cd ucsim-mcp
python3 -m venv .venv
. .venv/bin/activate
pip install -e ../pyucsim        # the client library (dependency)
pip install -e ".[dev]"          # the MCP server

Configuration

Environment variables set the defaults for new sessions:

Any of these can be overridden per-session via start_session arguments.

Run

# stdio transport (what MCP clients spawn)
python -m ucsim_mcp
# or, after install:
ucsim-mcp

MCP client configuration

The repo ships a ready-to-use mcp.json that invokes the ucsim-mcp console script by name — no hardcoded paths. For this to work the client must find ucsim-mcp on its PATH. The portable way to do that is to install it in an isolated environment with pipx:

pipx install /path/to/ucsim-mcp        # or: pipx install ucsim-mcp (once published)

{
  "mcpServers": {
    "ucsim": {
      "command": "ucsim-mcp",
      "args": [],
      "env": {
        "UCSIM_CPU": "51",
        "UCSIM_XTAL": "11.0592M"
      }
    }
  }
}

UCSIM_BINARY is optional — the server auto-discovers a ucsim_* / s51 binary on PATH. Set it only if your simulator lives somewhere unusual.

No install (run from a checkout) — use pipx run / uvx so the client needs no fixed venv path:

{
  "mcpServers": {
    "ucsim": {
      "command": "pipx",
      "args": ["run", "--spec", "/path/to/ucsim-mcp", "ucsim-mcp"]
    }
  }
}

(Replace pipx run --spec ... ucsim-mcp with uvx --from /path/to/ucsim-mcp ucsim-mcp if you prefer uv.)

Tools

Memory space names depend on the simulated CPU (for MCS-51: rom/code, iram, xram, sfr).

Hardware plugins (cl_hw)

ucSim peripherals can be loaded at runtime as shared objects built against the ucsim-plugin-sdk (loadhw, alias insmod). Two ways:

• At startup (recommended when the module must observe the first fetch): start_session(image=..., load_hw=["/path/adc.so", "/path/teachbox.so"]). Modules are loaded before the image and reset.

• At runtime: load_hardware(session_id, "/path/adc.so"). Returns the parsed id_string; drive it with set_hardware(session_id, "adc 0 0x80").

The plugin must be built against the same ucSim binary (the C++ ABI must match). list_hardware shows what's loaded.

Example flow

start_session(image="firmware.hex", cpu="51", xtal="11.0592M")  -> {"session_id": "sim1", ...}
reset(session_id="sim1")
read_memory(session_id="sim1", space="rom", start=0, end=15)
step(session_id="sim1", count=100)
get_state(session_id="sim1")
write_memory(session_id="sim1", space="iram", address=0x50, value=0x42)
stop_session(session_id="sim1")

Tests

. .venv/bin/activate
python -m pytest

Unit tests run without a simulator. Integration tests drive the real binary and auto-skip if UCSIM_BINARY (default: the local ucsim_51 build) or the test ROM is unavailable.

License

MIT.