# STM32 GDB Debugger [Health: Active]

**Category:** 📟 Embedded System  
**Repository:** https://github.com/Zeraissh/stm32-gdb-mcp  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/stm32-gdb-debugger

## Description
Debug STM32 firmware on real hardware via GDB + OpenOCD/ST-Link/J-Link with decoded results.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "stm32-gdb-debugger": {
    "command": "uvx",
    "args": ["stm32-gdb-mcp"]
  }
}
```

## Documentation

## What STM32 GDB Debugger does

STM32 GDB Debugger provides MCP tools for investigating STM32 firmware on physical hardware. It uses GDB together with a supported GDB server to communicate with debug probes and targets. Supported probe and server combinations include ST-Link, J-Link, and CMSIS-DAP through OpenOCD, as well as J-Link GDB Server and st-util.

The server covers the workflow from initial connection through diagnosis. It can detect a probe, suggest server arguments, build firmware, flash and run an image, control execution, inspect target state, and export a debug report. Results are decoded into structured data and may include `suggested_next_actions`, which gives an agent follow-up steps based on the observed state.

## How it works

The MCP process runs locally and communicates with the client over stdio. It starts an ARM-capable GDB executable and, when needed, a GDB server. Those processes communicate with the probe over USB and with one another over localhost TCP connections. The server can read an ELF file, SVD data, and build files from the firmware project.

A compact tool surface is enabled by default. Hidden tools remain available through `call(tool, args)`, while `tool_help` provides their schemas. Composite operations such as `flash_and_run` and `debug_until` combine several debugging steps into one request. Named sessions allow multiple boards to be managed with `list_sessions` and `close_session`.

## Setup and configuration

Install the package with `pip install stm32-gdb-mcp`, run it through an MCP client with `uvx stm32-gdb-mcp`, or use the repository's editable installation. The required host tools are `arm-none-eabi-gdb` or `gdb-multiarch`, plus at least one of `openocd`, `JLinkGDBServerCL`, or `st-util`. Set `STM32_GDB_MCP_GDB` when the ARM-capable GDB executable has a different name or location. The `stm32-gdb-mcp-check-env` command checks the environment and prints platform-specific installation commands.

The deployment utility can install the server, write IDE MCP configuration, and create a project-aware rules file. Manual setup is also available for any MCP client. Firmware projects should provide the ELF and, where needed, SVD and build files. The server writes reports or saved debug configuration only to paths selected by tools, along with temporary lock and state files.

## Tools and capabilities

- Detect probes, check the environment, suggest server arguments, reset targets, build firmware, and flash images.
- Run, halt, continue, step, set breakpoints, wait for stop events, and collect timed execution samples.
- Capture state, inspect memory and variables, read registers and stack frames, and decode peripheral registers from SVD data.
- Reconstruct fault context, map a faulting PC to source, diagnose HardFaults, and analyze stacks.
- Detect RTOS usage and inspect FreeRTOS tasks, stacks, and queues.
- Read RTT, SWO, and UART logs; configure SWO; and collect symbolized PC samples.
- Replay scenarios, batch operations, inspect session logs and metrics, and export debug reports.

## Limitations and notes

The target scope is STM32 devices using Cortex-M debugging workflows; it is not intended for RISC-V or ESP32 targets. A physical debug probe, compatible GDB server, and suitable firmware artifacts are required. Target inspection generally requires the MCU to be halted.

The server does not send data off the local machine during normal operation. An agent can explicitly invoke `report_issue`, which uses the local `gh` login to submit a GitHub issue containing the written description, environment summary, MCP version, and session tool journal and metrics. Serial ports are opened only when a UART log is requested.

_Full upstream README: https://allmcps.com/mcp/stm32-gdb-debugger/readme_