Skip to content
Back to search

embedded-debugger-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adancurusul--embedded-debugger-mcp/badge.svg)](/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)

  1. # Embedded Debugger MCP Server
  2. [![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](https://rust-lang.org)
  3. [![RMCP](https://img.shields.io/badge/RMCP-0.3.2-blue.svg)](https://github.com/modelcontextprotocol/rust-sdk)
  4. [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  5. Embedded Debugger MCP is a Rust server for embedded debugging through either
  6. probe-rs (native) or OpenOCD (via the GDB Remote Serial Protocol). It exposes a
  7. single MCP tool set for AI assistants — probe discovery, target control, memory,
  8. breakpoints, flash, RTT, and AI-facing crash diagnosis — plus a small CLI and
  9. bundled skill for a command-driven workflow without setting up an MCP client
  10. first.
  11. Language versions: [English](README.md) | [中文](README_zh.md)
  12. ## What It Provides
  13. - One MCP tool set over two interchangeable backends (probe-rs native, or
  14. OpenOCD via GDB RSP), chosen at connect. Validated on real ESP32-S3.
  15. - MCP tools for probe discovery, target connection, core control, memory access,
  16. breakpoints, flash programming, RTT communication, and crash diagnosis
  17. (`diagnose_fault`, `unwind_exception`).
  18. - CLI commands for environment checks, configuration inspection, probe listing,
  19. MCP serving, and skill prompt handoff.
  20. - A Codex/Claude Code compatible skill at `skills/embedded-debugger`.
  21. - Release checks covering rustfmt, clippy, tests, docs, packaging, and the STM32
  22. demo build.
  23. ## Architecture
  24. ```text
  25. MCP client or CLI
  26. |
  27. v
  28. embedded-debugger-mcp (one MCP tool set)
  29. |
  30. v
  31. DebugBackend: probe-rs (native) | OpenOCD (GDB RSP)
  32. |
  33. v
  34. debug probe / openocd -> target MCU
  35. ```
  36. ## Requirements
  37. - Rust stable toolchain.
  38. - A probe-rs compatible debug probe such as ST-Link, J-Link, DAPLink, Black
  39. Magic Probe, or a supported FTDI-based probe. Alternatively, a running
  40. `openocd` exposing its GDB port (e.g. openocd-esp32 for ESP32) to use the
  41. `openocd` backend.
  42. - A supported target chip and working SWD/JTAG wiring for hardware operations.
  43. - Nightly Rust plus `rust-src` for the bundled STM32 demo firmware check.
  44. ## Build
  45. ```bash
  46. git clone https://github.com/adancurusul/embedded-debugger-mcp.git
  47. cd embedded-debugger-mcp
  48. cargo build --release
  49. ```
  50. The binary is `target/release/embedded-debugger-mcp`.
  51. ## MCP Mode
  52. Run the server explicitly:
  53. ```bash
  54. embedded-debugger-mcp serve
  55. ```
  56. For compatibility, running `embedded-debugger-mcp` without a subcommand also
  57. serves MCP over stdio.
  58. Example MCP client configuration:
  59. ```json
  60. {
  61. "mcpServers": {
  62. "embedded-debugger": {
  63. "command": "/path/to/embedded-debugger-mcp/target/release/embedded-debugger-mcp",
  64. "args": ["serve"],
  65. "env": {
  66. "RUST_LOG": "info"
  67. }
  68. }
  69. }
  70. }
  71. ```
  72. On Windows, use the `.exe` path and Windows path separators.
  73. ## CLI And Skill Mode
  74. CLI mode is useful for setup checks, automation, and agent workflows before an
  75. MCP client is configured.
  76. ```bash
  77. embedded-debugger-mcp doctor
  78. embedded-debugger-mcp doctor --json
  79. embedded-debugger-mcp probes list
  80. embedded-debugger-mcp probes list --json
  81. embedded-debugger-mcp config generate
  82. embedded-debugger-mcp config validate
  83. embedded-debugger-mcp config show
  84. embedded-debugger-mcp skill print-prompt
  85. embedded-debugger-mcp skill install --target both
  86. ```
  87. The bundled skill lives in:
  88. ```text
  89. skills/embedded-debugger/
  90. ```
  91. It is written as a plain Codex skill and is also packaged for Claude Code with
  92. `.claude-plugin/plugin.json`. The skill starts with CLI checks and uses MCP
  93. tools only when an MCP client is available.
  94. Install the skill for Codex and Claude Code:
  95. ```bash
  96. embedded-debugger-mcp skill install --target both
  97. ```
  98. Preview or automate the install with JSON:
  99. ```bash
  100. embedded-debugger-mcp skill install --target both --dry-run --json
  101. embedded-debugger-mcp skill install --target both --force --json
  102. ```
  103. `--target` accepts `codex`, `claude`, or `both`. The command installs the Codex
  104. skill under `~/.codex/skills/embedded-debugger`, the Claude Code skill under
  105. `~/.claude/skills/embedded-debugger`, and a local Claude plugin-dir package under
  106. `~/.claude/plugins/local/embedded-debugger-mcp`. Existing directories are not
  107. replaced unless `--force` is passed.
  108. Trigger the Codex skill with a prompt such as:
  109. ```text
  110. Use $embedded-debugger to inspect my embedded target setup.
  111. ```
  112. Load the installed Claude Code plugin package:
  113. ```bash
  114. claude --plugin-dir ~/.claude/plugins/local/embedded-debugger-mcp --print '/embedded-debugger inspect my embedded target setup'
  115. ```
  116. For skill-only environments, the same `skills/embedded-debugger` directory can
  117. also be copied to a local skills directory.
  118. Validate the skill package:
  119. ```bash
  120. python3 .github/scripts/validate_skill.py skills/embedded-debugger
  121. python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/embedded-debugger
  122. claude plugin validate .
  123. embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json
  124. ```
  125. The first command validates the repository skill metadata, the second validates
  126. the standard `SKILL.md` layout when the Codex skill creator validator is
  127. installed, and the third validates the Claude Code plugin manifest.
  128. ## Backends
  129. The tools run over one of two interchangeable engines, selected at `connect`:
  130. - `backend: "probe-rs"` (default) — native probe-rs; full flash and RTT support.
  131. - `backend: "openocd"` (experimental) — connects to an already-running `openocd`
  132. over its GDB port (`openocd_address`, default `127.0.0.1:3333`) using the GDB
  133. Remote Serial Protocol. Intended for targets probe-rs does not cover (e.g.
  134. Xtensa ESP32 via openocd-esp32). Memory access and halt/run/step/reset are
  135. validated on real ESP32-S3; flash and RTT are probe-rs only. Register reads
  136. currently use ARM gdb register numbers, so PC/SP are wrong on Xtensa (known
  137. limitation); `diagnose_fault` and `unwind_exception` are Cortex-M specific.
  138. Start openocd with `gdb_memory_map disable`, otherwise it probes flash on the
  139. GDB connect, fails, and rejects the connection — e.g.
  140. `openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable"`.
  141. The AI sees the same tool set for both; only `connect` arguments change.
  142. ## MCP Tool Set
  143. Probe management:
  144. | Tool | Purpose |
  145. |------|---------|
  146. | `list_probes` | Discover connected debug probes. |
  147. | `connect` | Open a probe session for a target chip. |
  148. | `probe_info` | Show active session information. |
  149. Target control:
  150. | Tool | Purpose |
  151. |------|---------|
  152. | `halt` | Halt core execution. |
  153. | `run` | Resume execution. |
  154. | `reset` | Reset the core. Only the implemented hardware-style reset path is accepted. |
  155. | `step` | Single-step one instruction. |
  156. | `get_status` | Read core/session status. |
  157. | `disconnect` | Drop the session and clean up resources. |
  158. Memory and breakpoints:
  159. | Tool | Purpose |
  160. |------|---------|
  161. | `read_memory` | Read target memory with configured size/range limits. |
  162. | `write_memory` | Write target memory when enabled by configuration. |
  163. | `set_breakpoint` | Set a hardware breakpoint. |
  164. | `clear_breakpoint` | Clear a hardware breakpoint. |
  165. Diagnostics:
  166. | Tool | Purpose |
  167. |------|---------|
  168. | `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. |
  169. | `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`). |
  170. Flash:
  171. | Tool | Purpose |
  172. |------|---------|
  173. | `flash_erase` | Erase flash when erase permissions are enabled. |
  174. | `flash_program` | Program ELF, HEX, or BIN files through probe-rs flash algorithms. |
  175. | `flash_verify` | Compare raw expected data with target flash contents. |
  176. | `run_firmware` | Erase, program, reset/run, and optionally attach RTT. |
  177. RTT:
  178. | Tool | Purpose |
  179. |------|---------|
  180. | `rtt_attach` | Attach to a SEGGER RTT control block. |
  181. | `rtt_detach` | Detach RTT. |
  182. | `rtt_channels` | List discovered RTT channels. |
  183. | `rtt_read` | Read from an up channel with max byte and timeout limits. |
  184. | `rtt_write` | Write to a down channel. |
  185. ## Crash Diagnosis
  186. After a crash, halt the core and let the model reason over the evidence:
  187. 1. `halt`, then `diagnose_fault` — reads the Cortex-M SCB fault registers
  188. (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) plus PC/SP/LR in one call and returns a
  189. compact structured bundle with the set fault bits. It reports evidence; it
  190. does not assert a root cause.
  191. 2. `unwind_exception` with `elf_path` — maps the crash to source lines. On the
  192. probe-rs backend this is a full DWARF backtrace (function + `file:line` per
  193. frame); on the OpenOCD backend it reads the exception stack frame and maps
  194. the faulting PC / caller LR.
  195. Both are Cortex-M specific (SCB registers, ARM exception frame) and do not apply
  196. to Xtensa (ESP32) targets. The firmware must be built with debug info
  197. (`.debug_line`) for source mapping.
  198. ## Safety Notes
  199. - Flash erase is disabled unless `security.allow_flash_erase` or
  200. `flash.allow_erase` is enabled.
  201. - Memory writes are controlled by `security.allow_memory_write`.
  202. - Optional memory range restriction uses target memory regions in the
  203. configuration.
  204. - Firmware file paths are canonicalized, checked against
  205. `security.allowed_file_paths` when configured, and checked against size
  206. limits.
  207. - Sector erase by arbitrary address is rejected until target-specific sector
  208. mapping is implemented.
  209. - `flash_verify` supports raw data comparison. Use raw BIN files or hex data for
  210. file-based verification.
  211. Generate a starting configuration:
  212. ```bash
  213. embedded-debugger-mcp config generate > embedded-debugger.toml
  214. embedded-debugger-mcp --config embedded-debugger.toml config validate
  215. ```
  216. ## STM32 Demo
  217. The STM32 RTT demo is in `examples/STM32_demo`.
  218. ```bash
  219. cd examples/STM32_demo
  220. CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked
  221. ```
  222. The demo firmware shows multi-channel RTT communication and is intended as a
  223. hardware validation aid. See [examples/STM32_demo/README.md](examples/STM32_demo/README.md).
  224. ## Release Checks
  225. Run these before cutting a release:
  226. ```bash
  227. cargo fmt --all -- --check
  228. cargo clippy --locked --all-targets --all-features -- -D warnings
  229. cargo test --locked --all-targets --all-features
  230. RUSTDOCFLAGS="-D warnings" cargo doc --locked --all-features --no-deps
  231. cargo package --locked
  232. python3 .github/scripts/validate_skill.py skills/embedded-debugger
  233. claude plugin validate .
  234. embedded-debugger-mcp skill install --target both --home /tmp/embedded-debugger-skill-home --force --json
  235. (cd examples/STM32_demo && CARGO_TARGET_DIR=/tmp/embedded-debugger-mcp-stm32-target cargo +nightly check --locked)
  236. ```
  237. ## Acknowledgments
  238. - [probe-rs](https://probe.rs/) for embedded debug probe support.
  239. - [rmcp](https://github.com/modelcontextprotocol/rust-sdk) for the Rust MCP SDK.
  240. - [tokio](https://tokio.rs/) for the async runtime.
  241. ## License
  242. This project is licensed under the MIT License. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.