flashprobe-mcp

An MCP server for flashing and monitoring
embedded targets from any MCP client (Claude Code, Claude Desktop, …). It covers
the whole bench from one tool surface, over two backends:

• probe-rs — JTAG/SWD flashing + RTT or semihosting capture. Any
  probe-rs-supported chip: ESP (Xtensa + RISC-V),
  STM32, nRF, RP2040/RP2350, …
• espflash — UART flashing + serial capture for ESP32-family chips.

Output is decoded as defmt when the firmware uses it (defmt-rtt,
rtt-target, or esp-println's defmt-espflash) and plain text otherwise —
detected automatically from the ELF.

Why a server instead of the CLI

The win for an agent is bounded, early-exiting capture. probe-rs run /
espflash monitor never terminate on their own — an agent either forgets a
timeout and hangs, or sets one and burns the whole window every time. This
server stops the instant an expected line (or defmt error) appears — the
programmatic equivalent of watching the log and pressing Ctrl-C — and returns a
compact, cleaned result.

Build

cargo build --release
# binary at: target/release/flashprobe-mcp

probe-rs is a default-on feature. For a lean espflash-only (serial) build with a
much smaller dependency tree:

cargo build --release --no-default-features

The server speaks MCP over stdio.

Configure your MCP client

claude mcp add flashprobe -- /absolute/path/to/target/release/flashprobe-mcp

Or generic mcpServers JSON:

{
  "mcpServers": {
    "flashprobe": {
      "command": "/absolute/path/to/target/release/flashprobe-mcp"
    }
  }
}

Serial access needs your user in the dialout/uucp group; probe access needs
the probe-rs udev rules.

Choosing a backend (required)

Every flash/monitor call takes an explicit backend: "probe-rs" or
"espflash". Both work on ESP chips, and the right one depends on where the
firmware emits output — RTT/semihosting (probe-rs) vs UART (espflash). Picking the wrong
one flashes fine but shows no logs, so the server asks rather than guessing.

• defmt-rtt / rtt-target firmware → probe-rs
• semihosting / embedded-test firmware → probe-rs
• esp-println / UART firmware → espflash
• any non-ESP chip → probe-rs

Auto-detection

Everything except the backend is derived from the project on disk (no config
file, no state) and can be overridden per call:

So from a project directory, flash_monitor { "backend": "probe-rs", "stop": "ready" } flashes the built artifact to the detected chip and decodes defmt —
nothing else to pass.

Artifact detection uses the target_directory reported by cargo metadata.
If a build wrapper overrides CARGO_TARGET_DIR only for the build, that directory
may differ from what metadata reports when the MCP server runs. Pass the actual
artifact path explicitly: file_path for flash / flash_monitor, or elf for
monitor / rerun. For example, esp-hal's hil-test is built by xtask into the
repository-root target/, although metadata from hil-test/ reports its own
target/. For that workflow, pass the ELF path and chip explicitly.

Release is the usual thing to flash, but embedded projects routinely iterate on
an optimized debug build — the esp-generate template sets opt-level = "s" for
the dev profile precisely so it fits and runs. Picking whichever was built last
covers both, and fails safe: after a release build followed by an edit and a
plain cargo build, the debug binary is the one you meant, where preferring
release would have silently flashed the stale image.

Tools

All flash/monitor/device tools work on both backends (each using its native
mechanism); only list_ports is serial-specific.

Capture

flash_monitor, monitor, and rerun capture until the first of:

• stop — an unanchored regex on the rendered line (RESULT (PASS|FAIL),
  panic|abort). Plain text is a valid pattern.
• stop_on_level — defmt only: stop on the first frame at/above a level
  (e.g. error) — the "did it panic?" button.
• idle_ms — no new data for this long (default 4000).
• timeout_s — max wall-clock window (default 5).
• max_bytes — byte cap; stops early and marks the output truncated
  (default 65536). Reads arrive in chunks, so a capture stops just past the
  cap: a reported byte count above max_bytes is expected, not a miscount.

For probe-rs captures, transport accepts "auto" (default), "rtt", or
"semihosting". Auto uses RTT when the ELF defines _SEGGER_RTT, otherwise
semihosting. Without an ELF, auto retains RTT RAM scanning; pass an ELF or
force semihosting for a console-only application. The output header reports
via RTT or via semihosting. An unreadable/invalid ELF is an error, not an
auto-detection fallback. rtt_attach_timeout_ms applies only to RTT.

Semihosting uses probe-rs library requests for console writes, stdout/stderr,
command line, time, errno and exit. Console data uses text decoding even if the
ELF contains a defmt table. stop, grep, context, idle/timeout/byte limits,
ANSI/noise filtering and empty/truncated reporting share the normal capture
pipeline. stop_on_level, level and module need defmt metadata and do not
apply to this text stream. Target exit ends capture without waiting for idle.
File access and stdin/send are unsupported. A semihosting flush is a no-op:
servicing a pending syscall would execute firmware and consume fresh output.

An ELF with embedded-test protocol 1 metadata (embedded-test >= 0.7) runs as a
test suite: the host supplies each test address, resets between tests, honours
ignored tests, expected panics and per-test timeouts, and emits test NAME ... ok/FAILED plus test result: .... Earlier/future protocol versions produce an
explicit error. For embedded-test only, monitor also starts a fresh suite,
resetting before the first test as well as between tests. A detached ESP may already have treated
the semihosting trap as an exception, so attach-only cannot reliably recover its
test command. Ordinary semihosting applications still attach without reset.
rerun resets and runs the entire suite per repeat. A failed test remains
visible in the text; matching test result: means completion, not test success.
Set a capture window long enough for the entire suite, for example:

{"backend":"probe-rs","chip":"esp32c5","elf":"/path/to/misc_drivers",
 "stop":"test result:","timeout_s":200,"idle_ms":65000,"repeat":3}

Use this with rerun; for flash_monitor use file_path instead of elf and
omit repeat. Semihosting polling services core 0; multicore console capture is
not implemented. Stopping a capture stops host servicing, so firmware can block
at its next semihosting request until another monitor attaches.

Hardware evidence and reproducible MCP stdio commands are in
docs/semihosting.md.

For probe-rs RTT boot capture, the server temporarily makes the RTT up-channel
blocking to preserve the earliest frames, then restores the firmware's original
channel mode when capture ends.

After a reset the server waits up to rtt_attach_timeout_ms (default 1500)
for the firmware to initialize RTT. An ESP32-C5 booting through the ESP-IDF
bootloader was measured attaching in under 200 ms, so the default has ample
headroom while still reporting a firmware that never brings RTT up. Raise it for
a target whose bootloader runs materially longer.

Show filters: grep (regex, both modes), context (N lines around the
stop match), and defmt-only level (minimum to show) / module (regex on the
module path). In defmt mode a suppressed-by-level count reports what a looser
level would reveal. In text mode, ROM/bootloader boot noise (strip_boot_noise)
and ANSI codes (strip_ansi) are stripped by default.

When a capture comes back empty

An empty capture has three distinct causes, and the output names which one it
was rather than leaving you to guess:

• (nothing was received) — no bytes arrived at all. Loosening the filters
  cannot help. What follows depends on whether the capture reset the target:
  • After monitor, the usual cause is a target that prints at boot and then
    idles. monitor only sees what is sent after it attaches; use rerun or
    flash_monitor, which reset first and capture from the start.
  • After rerun or flash_monitor, the target was reset and still said
    nothing. Either it is not running, or it logs where this backend is not
    listening — RTT firmware produces nothing on the serial backend, and vice
    versa. Check backend first; it is the most common mistake.
• (bytes arrived, but every line was removed by the filters) — the data is
  there. Relax level, module or grep. In defmt mode the header also
  reports how many frames a looser level would reveal.
• (no application output — only boot/ROM noise was captured) — text mode
  only: bytes arrived but strip_boot_noise removed all of them. Set it to
  false to see the raw stream.

A capture that ran after another capture already drained the buffer is not a
failure either: rerun consumes the output it captures, so a monitor right
afterwards has genuinely nothing left to show for firmware that prints once.

Known target quirks

• ESP32-C5 over USB-Serial-JTAG. espflash's DTR/RTS reset leaves this board
  in download mode rather than booting the application, so rerun and
  flash_monitor on the espflash backend capture nothing from it — the
  application never starts. Reset or flash through probe-rs to boot it
  normally. The serial backend still reads fine; it is the reset that differs.

Sending to the target

The same three tools take send, a string written to the device before the
read loop, so a command and its reply fit in one call:

{ "backend": "probe-rs", "send": "status\n", "stop": "OK|ERR" }

It goes out on the RTT down-channel 0 (probe-rs) or the serial TX line
(espflash). The escapes \n \r \t \0 \xNN \\ are interpreted —
line-based firmware almost always needs the trailing \n. Ordering is fixed at
flush → send → read, so the flush can never eat the reply. Pair it with stop
to return the instant the answer arrives.

send_delay_ms (default 0) waits before sending. Serial has no target-side
buffer, so bytes that arrive before the firmware's RX is listening are lost —
give a just-reset or just-flashed device time to boot. RTT needs this less: the
bytes sit in the target's ring buffer until the firmware reads them.

probe-rs needs a firmware down-channel. defmt-rtt declares
max_down_channels = 0, so it can never receive host input and send reports
that. Use rtt-target with an explicit down-channel; defmt still works there
through set_defmt_channel:

let channels = rtt_init! {
    up:   { 0: { size: 1024, mode: NoBlockSkip, name: "defmt" } },
    down: { 0: { size: 64, name: "input" } }
};
set_defmt_channel(channels.up.0);

defmt note

defmt decode needs the exact ELF that's running — version skew yields
garbage, not an error. It's free in the flash-then-monitor flow (just built it);
for bare monitor/rerun, make sure the auto-detected (or passed) ELF matches.
The server surfaces a warning when a non-empty stream decodes to zero frames.

On the serial backend, defmt frames are marker-delimited (0xFF 0x00) precisely
so they can share the line with plain text, and both are shown. That matters
because the ROM and the ESP-IDF bootloader print text long before the
application's first frame: a target that dies in the bootloader still tells you
why, instead of looking like a target that said nothing.

License

MIT — see LICENSE.