Embedded Debugger MCP

What adancurusul/embedded-debugger-mcp MCP server does

The adancurusul/embedded-debugger-mcp MCP server provides one tool set for embedded target control through two backends: native probe-rs and OpenOCD through the GDB Remote Serial Protocol. It is designed for hardware debugging workflows involving supported debug probes, target chips, and working SWD or JTAG wiring.

The server covers the full session lifecycle. An agent can find connected probes, connect to a target, inspect the active session, halt or resume execution, reset and single-step the core, read status, and disconnect cleanly. Memory access, hardware breakpoints, flash operations, and SEGGER RTT communication are also exposed.

Cortex-M crash workflows include reading SCB fault registers together with PC, SP, and LR, then unwinding an exception and mapping frames to source lines. These calls report evidence for analysis rather than claiming a definitive root cause.

How it works

The client communicates with a single MCP tool set, while the selected backend performs the hardware operations. The default probe-rs backend supports native probe access, flash programming, and RTT. The experimental openocd backend connects to an already running OpenOCD instance, using 127.0.0.1:3333 by default, and is intended in part for targets not covered by probe-rs, such as Xtensa ESP32 devices through openocd-esp32.

The backend is selected in the connect call. OpenOCD support has been validated for memory access and halt, run, step, and reset operations on an ESP32-S3. Flash and RTT are limited to the probe-rs backend. Cortex-M-specific fault diagnosis and exception unwinding do not apply to Xtensa targets.

Setup and configuration

Build the Rust project with a stable Rust toolchain:

cargo build --release

The resulting executable is target/release/embedded-debugger-mcp. Run embedded-debugger-mcp serve to expose MCP over standard input and output; invoking the executable without a subcommand also starts MCP mode. An MCP client configuration can point its command to that binary and pass serve as an argument.

A probe-rs setup needs a compatible probe, such as an ST-Link, J-Link, DAPLink, Black Magic Probe, or supported FTDI-based probe, plus a supported target and suitable wiring. The OpenOCD path requires a running OpenOCD process with a reachable GDB port. Its configuration must disable the GDB memory map probing; the README gives gdb_memory_map disable as the required setting for the documented ESP32-S3 example.

Tools and capabilities

The adancurusul/embedded-debugger-mcp MCP server exposes tools for:

• Probe discovery, connection details, session status, and cleanup.
• Core halt, resume, reset, single-step, memory reads, optional memory writes, and hardware breakpoints.
• Flash erase, ELF/HEX/BIN programming, raw verification, and combined firmware deployment with optional RTT attachment.
• RTT attachment, detachment, channel discovery, and bounded reads and writes.
• Cortex-M fault-register collection and source-aware exception unwinding when an ELF with debug-line information is available.

The repository also includes CLI commands for diagnostics, configuration inspection, probe listing, MCP serving, and installing its bundled workflow skill for Codex or Claude Code.

Limitations and notes

Write-memory and flash-erase behavior depend on configuration permissions. Fault diagnosis should be run after halting the target. Exception unwinding needs an elf_path pointing to firmware built with debug information, including .debug_line. On OpenOCD, register reads currently use ARM GDB register numbers, so PC and SP are incorrect on Xtensa. The project has been validated on real ESP32-S3 hardware, but support still depends on the selected backend, probe, target, and wiring.