Log inSubmit server
STM32 GDB Debugger logo

STM32 GDB Debugger

Debug STM32 firmware on hardware through GDB and OpenOCD, ST-Link, J-Link, or st-util with decoded results.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install STM32 GDB Debugger

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "stm32-gdb-debugger": {
      "command": "uvx",
      "args": [
        "stm32-gdb-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

STM32 GDB Debugger MCP server connects an AI agent to STM32 hardware through ARM-capable GDB and a GDB server such as OpenOCD, J-Link GDB Server, or st-util. It exposes tools for flashing, execution control, breakpoints, memory and register inspection, RTOS analysis, fault diagnosis, logging, and profiling, returning structured evidence rather than raw GDB output. Use it when firmware is running on a real STM32 target and you want repeatable debugging workflows, decoded HardFault analysis, or multi-board sessions. The server runs locally over stdio and requires the relevant GDB and probe software on PATH.

Use cases

  • Flash and run STM32 firmware on a connected board
  • Diagnose HardFaults and map fault addresses to source
  • Inspect FreeRTOS tasks, stacks, and queues
  • Decode peripheral registers using SVD files
  • Replay debugging scenarios and export reports

Key features

  • Structured GDB results with suggested next actions
  • OpenOCD, J-Link GDB Server, and st-util support
  • HardFault reconstruction and stack analysis
  • FreeRTOS inspection and SVD peripheral decoding
  • RTT, SWO, UART logging, and symbolized PC sampling
  • Multi-board named sessions and replay workflows

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · stm32-gdb-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
Last commit5d agoMost recent push to the default branch.

How STM32 GDB Debugger works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about STM32 GDB Debugger

STM32 GDB Debugger is an MCP server that connects AI agents to STM32 hardware through ARM-capable GDB and GDB servers such as OpenOCD, J-Link GDB Server, or st-util. Its main tools flash firmware, control execution, inspect memory and registers, analyze faults and RTOS state, read logs, and export decoded debug evidence.

Install it with `pip install stm32-gdb-mcp` or run `uvx stm32-gdb-mcp` from an MCP client. You can also use `pip install -e .` for a repository checkout. The deployment utility writes IDE configuration, while `stm32-gdb-mcp-check-env` checks required host tools.

It requires an STM32 target, a compatible debug probe, an ARM-capable GDB, and at least one GDB server. Supported server choices include OpenOCD, J-Link GDB Server, and st-util. ST-Link, J-Link, and CMSIS-DAP probes are supported through the corresponding server software.

Yes. Its fault tools reconstruct fault context, analyze the stack, and connect the faulting program counter to source information. The returned data is decoded and can include suggested next actions for continuing the investigation.

Yes. Cursor is named as a supported installation target. The deployment command can install the server and write IDE MCP configuration, or you can configure the stdio command manually in Cursor.

Related MCP servers

All in Embedded System All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewSTM32 GDB Debugger AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/stm32-gdb-debugger?style=directory)](https://allmcps.com/mcp/stm32-gdb-debugger)
HTML Embed
<a href="https://allmcps.com/mcp/stm32-gdb-debugger"><img src="https://allmcps.com/api/badge/stm32-gdb-debugger?style=directory" alt="STM32 GDB Debugger on AllMCPs" /></a>