Back to search
embedded-debugger-mcp
SkillGitHub
MCP server + CLI + Codex/Claude skill for embedded debugging via probe-rs or OpenOCD — ARM Cortex-M, RISC-V, and Xtensa (ESP32), with AI crash diagnosis
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/adancurusul--embedded-debugger-mcp)HTML
<a href="/listings/adancurusul--embedded-debugger-mcp"><img src="/api/listings/adancurusul--embedded-debugger-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 316 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Embedded Debugger MCP Server
- [](https://rust-lang.org)
- [](https://github.com/modelcontextprotocol/rust-sdk)
- [](LICENSE)
- 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](README.md) | [中文](README_zh.md)
- ## 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
- ```text
- MCP client or CLI
- |
- v
- embedded-debugger-mcp (one MCP tool set)
- |
- v
- DebugBackend: probe-rs (native) | OpenOCD (GDB RSP)
- |
- v
- debug probe / openocd -> target MCU
- ```
- ## 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
- ```bash
- git clone https://github.com/adancurusul/embedded-debugger-mcp.git
- cd embedded-debugger-mcp
- cargo build --release
- ```
- The binary is `target/release/embedded-debugger-mcp`.
- ## MCP Mode
- Run the server explicitly:
- ```bash
- embedded-debugger-mcp serve
- ```
- For compatibility, running `embedded-debugger-mcp` without a subcommand also
- serves MCP over stdio.
- Example MCP client configuration:
- ```json
- {
- "mcpServers": {
- "embedded-debugger": {
- "command": "/path/to/embedded-debugger-mcp/target/release/embedded-debugger-mcp",
- "args": ["serve"],
- "env": {
- "RUST_LOG": "info"
- }
- }
- }
- }
- ```
- 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.
- ```bash
- embedded-debugger-mcp doctor
- embedded-debugger-mcp doctor --json
- embedded-debugger-mcp probes list
- embedded-debugger-mcp probes list --json
- embedded-debugger-mcp config generate
- embedded-debugger-mcp config validate
- embedded-debugger-mcp config show
- embedded-debugger-mcp skill print-prompt
- embedded-debugger-mcp skill install --target both
- ```
- The bundled skill lives in:
- ```text
- skills/embedded-debugger/
- ```
- 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:
- ```bash
- embedded-debugger-mcp skill install --target both
- ```
- Preview or automate the install with JSON:
- ```bash
- embedded-debugger-mcp skill install --target both --dry-run --json
- embedded-debugger-mcp skill install --target both --force --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:
- ```text
- Use $embedded-debugger to inspect my embedded target setup.
- ```
- Load the installed Claude Code plugin package:
- ```bash
- claude --plugin-dir ~/.claude/plugins/local/embedded-debugger-mcp --print '/embedded-debugger inspect my embedded target setup'
- ```
- For skill-only environments, the same `skills/embedded-debugger` directory can
- also be copied to a local skills directory.
- Validate the skill package:
- ```bash
- python3 .github/scripts/validate_skill.py skills/embedded-debugger
- python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/embedded-debugger
- claude plugin validate .
- embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json
- ```
- 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
- currently use ARM gdb register numbers, so PC/SP are wrong on Xtensa (known
- limitation); `diagnose_fault` and `unwind_exception` are Cortex-M specific.
- Start openocd with `gdb_memory_map disable`, otherwise it probes flash on the
- GDB connect, fails, and rejects the connection — e.g.
- `openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable"`.
- The AI sees the same tool set for both; only `connect` arguments change.
- ## MCP Tool Set
- Probe management:
- | Tool | Purpose |
- |------|---------|
- | `list_probes` | Discover connected debug probes. |
- | `connect` | Open a probe session for a target chip. |
- | `probe_info` | Show active session information. |
- Target control:
- | Tool | Purpose |
- |------|---------|
- | `halt` | Halt core execution. |
- | `run` | Resume execution. |
- | `reset` | Reset the core. Only the implemented hardware-style reset path is accepted. |
- | `step` | Single-step one instruction. |
- | `get_status` | Read core/session status. |
- | `disconnect` | Drop the session and clean up resources. |
- Memory and breakpoints:
- | Tool | Purpose |
- |------|---------|
- | `read_memory` | Read target memory with configured size/range limits. |
- | `write_memory` | Write target memory when enabled by configuration. |
- | `set_breakpoint` | Set a hardware breakpoint. |
- | `clear_breakpoint` | Clear a hardware breakpoint. |
- Diagnostics:
- | Tool | Purpose |
- |------|---------|
- | `diagnose_fault` | Read the Cortex-M SCB fault registers (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR in one call and return a compact structured evidence bundle with the set fault bits. Reports raw evidence; it does not assert a root cause. Halt the target first. |
- | `unwind_exception` | Unwind the stack after a crash and map each frame to a source line. On the probe-rs backend, returns a full DWARF backtrace (function + file:line per frame) via probe-rs's own unwinder; on the OpenOCD backend, reads the Cortex-M exception stack frame and maps the faulting PC / caller LR to source lines. Needs `elf_path` to firmware built with debug info (`.debug_line`). |
- Flash:
- | Tool | Purpose |
- |------|---------|
- | `flash_erase` | Erase flash when erase permissions are enabled. |
- | `flash_program` | Program ELF, HEX, or BIN files through probe-rs flash algorithms. |
- | `flash_verify` | Compare raw expected data with target flash contents. |
- | `run_firmware` | Erase, program, reset/run, and optionally attach RTT. |
- RTT:
- | Tool | Purpose |
- |------|---------|
- | `rtt_attach` | Attach to a SEGGER RTT control block. |
- | `rtt_detach` | Detach RTT. |
- | `rtt_channels` | List discovered RTT channels. |
- | `rtt_read` | Read from an up channel with max byte and timeout limits. |
- | `rtt_write` | Write to a down channel. |
- ## Crash Diagnosis
- After a crash, halt the core and let the model reason over the evidence:
- 1. `halt`, then `diagnose_fault` — reads the Cortex-M SCB fault registers
- (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR in one call and returns a
- compact structured bundle with the set fault bits. It reports evidence; it
- does not assert a root cause.
- 2. `unwind_exception` with `elf_path` — maps the crash to source lines. On the
- probe-rs backend this is a full DWARF backtrace (function + `file:line` per
- frame); on the OpenOCD backend it reads the exception stack frame and maps
- the faulting PC / caller LR.
- Both are Cortex-M specific (SCB registers, ARM exception frame) and do not apply
- to Xtensa (ESP32) targets. The firmware must be built with debug info
- (`.debug_line`) for source mapping.
- ## Safety Notes
- - Flash erase is disabled unless `security.allow_flash_erase` or
- `flash.allow_erase` is enabled.
- - Memory writes are controlled by `security.allow_memory_write`.
- - Optional memory range restriction uses target memory regions in the
- configuration.
- - Firmware file paths are canonicalized, checked against
- `security.allowed_file_paths` when configured, and checked against size
- limits.
- - Sector erase by arbitrary address is rejected until target-specific sector
- mapping is implemented.
- - `flash_verify` supports raw data comparison. Use raw BIN files or hex data for
- file-based verification.
- Generate a starting configuration:
- ```bash
- embedded-debugger-mcp config generate > embedded-debugger.toml
- embedded-debugger-mcp --config embedded-debugger.toml config validate
- ```
- ## STM32 Demo
- The STM32 RTT demo is in `examples/STM32_demo`.
- ```bash
- cd examples/STM32_demo
- CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked
- ```
- The demo firmware shows multi-channel RTT communication and is intended as a
- hardware validation aid. See [examples/STM32_demo/README.md](examples/STM32_demo/README.md).
- ## Release Checks
- Run these before cutting a release:
- ```bash
- cargo fmt --all -- --check
- cargo clippy --locked --all-targets --all-features -- -D warnings
- cargo test --locked --all-targets --all-features
- RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
- cargo package --locked
- python3 .github/scripts/validate_skill.py skills/embedded-debugger
- claude plugin validate .
- embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json
- (cd examples/STM32_demo && CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked)
- ```
- ## Acknowledgments
- - [probe-rs](https://probe.rs/) for embedded debug probe support.
- - [rmcp](https://github.com/modelcontextprotocol/rust-sdk) for the Rust MCP SDK.
- - [tokio](https://tokio.rs/) for the async runtime.
- ## License
- This project is licensed under the MIT License. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.