adancurusul/embedded-debugger-mcp

Embedded Debugger MCP is a Rust server for embedded debugging through either
probe-rs (native) or OpenOCD (via the GDB Remote Serial Protocol). It exposes a
single MCP tool set for AI assistants — probe discovery, target control, memory,
breakpoints, flash, RTT, and AI-facing crash diagnosis — plus a small CLI and
bundled skill for a command-driven workflow without setting up an MCP client
first.
Language versions: English | 中文
What It Provides
- One MCP tool set over two interchangeable backends (probe-rs native, or
OpenOCD via GDB RSP), chosen at connect. Validated on real ESP32-S3.
- MCP tools for probe discovery, target connection, core control, memory access,
breakpoints, flash programming, RTT communication, and crash diagnosis
(diagnose_fault, unwind_exception).
- CLI commands for environment checks, configuration inspection, probe listing,
MCP serving, and skill prompt handoff.
- A Codex/Claude Code compatible skill at skills/embedded-debugger.
- Release checks covering rustfmt, clippy, tests, docs, packaging, and the STM32
demo build.
Architecture
Requirements
- Rust stable toolchain.
- A probe-rs compatible debug probe such as ST-Link, J-Link, DAPLink, Black
Magic Probe, or a supported FTDI-based probe. Alternatively, a running
openocd exposing its GDB port (e.g. openocd-esp32 for ESP32) to use the
openocd backend.
- A supported target chip and working SWD/JTAG wiring for hardware operations.
- Nightly Rust plus rust-src for the bundled STM32 demo firmware check.
Build
The binary is target/release/embedded-debugger-mcp.
MCP Mode
Run the server explicitly:
For compatibility, running embedded-debugger-mcp without a subcommand also
serves MCP over stdio.
Example MCP client configuration:
On Windows, use the .exe path and Windows path separators.
CLI And Skill Mode
CLI mode is useful for setup checks, automation, and agent workflows before an
MCP client is configured.
The bundled skill lives in:
It is written as a plain Codex skill and is also packaged for Claude Code with
.claude-plugin/plugin.json. The skill starts with CLI checks and uses MCP
tools only when an MCP client is available.
Install the skill for Codex and Claude Code:
Preview or automate the install with JSON:
--target accepts codex, claude, or both. The command installs the Codex
skill under ~/.codex/skills/embedded-debugger, the Claude Code skill under
~/.claude/skills/embedded-debugger, and a local Claude plugin-dir package under
~/.claude/plugins/local/embedded-debugger-mcp. Existing directories are not
replaced unless --force is passed.
Trigger the Codex skill with a prompt such as:
Load the installed Claude Code plugin package:
For skill-only environments, the same skills/embedded-debugger directory can
also be copied to a local skills directory.
Validate the skill package:
The first command validates the repository skill metadata, the second validates
the standard SKILL.md layout when the Codex skill creator validator is
installed, and the third validates the Claude Code plugin manifest.
Backends
The tools run over one of two interchangeable engines, selected at connect:
- backend: "probe-rs" (default) — native probe-rs; full flash and RTT support.
- backend: "openocd" (experimental) — connects to an already-running openocd
over its GDB port (openocd_address, default 127.0.0.1:3333) using the GDB
Remote Serial Protocol. Intended for targets probe-rs does not cover (e.g.
Xtensa ESP32 via openocd-esp32). Memory access and halt/run/step/reset are
validated on real ESP32-S3; flash and RTT are probe-rs only. Register reads