SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingembedded-debugger-mcp

embedded-debugger-mcp

📟 - Embedded debugging with probe-rs: ARM Cortex-M and RISC-V targets via J-Link, ST-Link and other probes.

Open website

About this tool

Embedded Debugger MCP Server is an embedded debugging server written in Rust. Through two interchangeable backends, probe-rs (native) or OpenOCD (via GDB Remote Serial Protocol), it exposes a single MCP tool set to AI assistants, along with a small CLI and a bundled skill for command-driven workflows, usable without first configuring an MCP client. The material shows that the project has been verified on a real ESP32-S3.

Purpose and Positioning This tool is aimed at embedded development and debugging scenarios, enabling AI assistants to directly perform probe discovery, target connection, core control, memory access, breakpoint setting, Flash programming, RTT communication, and crash diagnosis. It also provides CLI commands for environment checks, configuration viewing, probe listing, MCP service startup, and skill prompt handoff.

Main Capabilities

  • One MCP tool set, two interchangeable backends (probe-rs native, or OpenOCD via GDB RSP), selected at connect time.
  • MCP tools cover: probe discovery, target connection, core control, memory access, breakpoints, Flash programming, RTT communication, crash diagnosis (diagnose_fault, unwind_exception).
  • CLI commands for environment checks, configuration checks, probe listing, MCP service, and skill prompt handoff.
  • A Codex/Claude Code compatible skill is provided at skills/embedded-debugger.
  • Release checks cover rustfmt, clippy, tests, docs, packaging, and the STM32 demo build.

Backends and Tool Capabilities The tools run on one of two interchangeable engines, selected at connect time:

  • backend: "probe-rs" (default) — native probe-rs; full Flash and RTT support.
  • backend: "openocd" (experimental) — connects via GDB Remote Serial Protocol to the GDB port of an already running openocd (openocd_address, default 127.0.0.1:3333). Aimed at targets not covered by probe-rs (for example, Xtensa ESP32 via openocd-esp32). Memory access and halt/run/step/reset have been verified on a real ESP32-S3; Flash and RTT are limited to probe-rs. Register reads currently use ARM gdb register numbers, so PC/SP are incorrect on Xtensa (a known limitation); diagnose_fault and unwind_exception are Cortex-M specific. When starting openocd, you need to add gdb_memory_map disable, otherwise it will probe Flash when GDB connects, fail, and refuse the connection — for example, openocd -f board/esp32s3-builtin.cfg -c "gdb_memory_map disable". The AI sees the same tool set under both backends, and only the connect parameters change.

Crash Diagnosis After a crash, halt the core and let the model reason about the evidence:

  • halt, then diagnose_fault — in a single call, read the Cortex-M SCB fault registers (CFSR/HFSR/MMFAR/BFAR/SHCSR/CPUID) as well as PC/SP/LR, and return a compact structured packet containing the fault bits that are set. It reports evidence and does not assert a root cause.
  • unwind_exception with elf_path — maps the crash to source lines. On the probe-rs backend this is a full DWARF backtrace (each frame includes function + file:line); 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. Firmware must be built with debug information (.debug_line) for source mapping.

Security and Limitations

  • 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 restrictions use the target memory regions in the configuration.
  • Firmware file paths are normalized, and configurationWhen security.allowed_file_paths is set, it is checked, along with the size limit.
  • Before a target-specific sector map is implemented, sector erase at an arbitrary address is rejected.
  • flash_verify supports raw data comparison. For file-based verification, use a raw BIN file or hexadecimal data.

Usage A Rust stable toolchain is required. On the hardware side, a probe-rs compatible debug probe is required, such as ST-Link, J-Link, DAPLink, Black Magic Probe, or a supported FTDI-based probe; or a running openocd that exposes its GDB port (for example openocd-esp32 for ESP32) to use the openocd backend. A supported target chip and working SWD/JTAG wiring are also required. The bundled STM32 demo firmware check requires nightly Rust plus rust-src. The binary is located at target/release/embedded-debugger-mcp. Running the server can be done explicitly; for compatibility, running embedded-debugger-mcp without a subcommand also serves MCP over stdio. On Windows, use the .exe path and Windows path separators. The configuration example shows the MCP client configuration.

CLI and Skill Mode CLI mode is suitable for setup checks, automation, and agent workflows before configuring an MCP client. The bundled skill is located at skills/embedded-debugger, is written as a plain Codex skill, and is packaged as a Claude Code version via .claude-plugin/plugin.json. The skill starts with CLI checks and uses MCP tools only when an MCP client is available. Installing the skill uses a command; --target accepts codex, claude, or both, installing to ~/.codex/skills/embedded-debugger, ~/.claude/skills/embedded-debugger, and ~/.claude/plugins/local/embedded-debugger-mcp respectively. Unless you passin --force, existing directories are not replaced. The Codex skill can be triggered via a prompt, loading the installed Claude Code plugin package. In a skill-only environment, the skills/embedded-debugger directory can also be copied to the local skills directory. The skill package verification command separately verifies the repository skill metadata, the standard SKILL.md layout, and the Claude Code plugin manifest.

Examples and Checks Generate the initial configuration using the corresponding command. The STM32 RTT demo is located at examples/STM32_demo, demonstrates multi-channel RTT communication, and serves as a hardware verification aid; see examples/STM32_demo/README.md. Run the specified check command before release.

Acknowledgements and License Acknowledgements to probe-rs (embedded debug probe support), rmcp (Rust MCP SDK), tokio (async runtime). This project is licensed under the MIT License; see LICENSE.

Related tools

Browse category