stm32-stlink-mcp

MCP server for debugging STM32 microcontrollers over ST-LINK, built on STMicroelectronics' own STM32CubeCLT toolset — ST-LINK_gdbserver, STM32_Programmer_CLI, and arm-none-eabi-gdb (driven via GDB/MI2). No OpenOCD, J-Link, or probe-rs involved.

Architecture

A debug session is a pair of child processes, exactly mirroring ST's own documented workflow (UM2576, "STM32CubeIDE ST-LINK GDB server"):

 arm-none-eabi-gdb  --interpreter=mi2  --(TCP, target extended-remote)-->  ST-LINK_gdbserver  --(USB)-->  ST-LINK  --(SWD)-->  STM32

arm-none-eabi-gdb is driven in MI2 mode so the server gets source-level stepping, symbolic breakpoints, and symbol-aware expression evaluation for free, instead of hand-rolling the GDB Remote Serial Protocol. ST-LINK_gdbserver owns the USB handle to the probe for the lifetime of the session; flashing via gdb's load (MI: -target-download) is transparently delegated by the server to STM32CubeProgrammer, so no session teardown is needed to reflash. A standalone one-shot flash (flash_standalone, no session required) invokes STM32_Programmer_CLI directly and therefore conflicts with an already-open session on the same probe — see the tool description.

Related MCP server: dbgprobe-mcp-server

Setup

npm install
npm run build

Requires STM32CubeCLT to be installed and its bin/ directories reachable — either already on PATH (the CLT installer does this by default) or via STMCP_CUBECLT_PATH / per-tool overrides. Run npm run doctor to check.

Running

node dist/index.js serve     # starts the MCP server on stdio (default mode)
node dist/index.js doctor    # pre-flight check: tool resolution, connected probes, udev rules
node dist/index.js doctor --json

Registering with an MCP client

{
  "mcpServers": {
    "stm32-stlink": {
      "command": "node",
      "args": ["<path-to-this-repo>/stmcp/dist/index.js"]
    }
  }
}

Configuration (environment variables)

Tools

Deferred to v2

SVD peripheral register tools (memory_read/write + evaluate_expression already reach everything by address), live/streaming memory polling, a plugin system, per-chip memory-region allowlists, arbitrary gdb monitor passthrough, and option-bytes/RDP tools (bricking-capable, intentionally out of scope).

RTT

RTT (SEGGER Real Time Transfer — live, non-halting console/variable tracing) is intentionally not implemented in this server. ST-LINK_gdbserver's GDB/MI stub has no non-stop mode, so reading memory through this server's debug_connect session requires halting the core first — which defeats RTT's purpose. The correct mechanism is direct AP memory access that never halts the core (confirmed by reading ST's own STM32CubeMonitor source, which uses exactly this, and by STM32_Programmer_CLI's -r32fast).

That's what strtt already does, and strtt-mcp wraps it as its own MCP server (strtt_start/strtt_stop/strtt_status/strtt_read/strtt_write). Register it alongside this server rather than through it:

{
  "mcpServers": {
    "stm32-stlink": { "command": "node", "args": ["<...>/mcp-server/dist/index.js"] },
    "strtt": {
      "command": "node",
      "args": ["<path-to-strtt-repo>/mcp/dist/index.js"],
      "env": { "STRTT_BIN": "<path-to-strtt-binary>" }
    }
  }
}

Start strtt_start with tcp: true to connect through the shared ST-LINK Server instead of claiming the USB device directly — this lets it run concurrently with an open debug_connect session here, since GdbServerProcess always passes -t/--shared to ST-LINK_gdbserver. Without tcp: true, strtt and an open debug session will contend for the same probe.

Hardware verification runbook

With an ST-LINK and target attached:

node dist/index.js doctor                     # confirm probe + tools resolve
npx @modelcontextprotocol/inspector node dist/index.js   # interactive tool testing

Then, via the inspector or an MCP client:

1. list_probes → the probe's serial appears.

2. debug_connect { elfPath, device, interface: "swd", serial } → returns a sessionId.

3. breakpoint_set { sessionId, location: "main" } → returns a breakpoint number.

4. debug_run { sessionId } → halts with reason: "breakpoint-hit".

5. register_read { sessionId, registers: ["pc","sp","lr","r0"] }.

6. evaluate_expression { sessionId, expression: "<a known global>" }.

7. read_fault_registers { sessionId } → benign/zero flags right after reset.

8. debug_disconnect { sessionId } → confirm no orphaned processes: ps aux | grep -E 'ST-LINK_gdbserver|arm-none-eabi-gdb'.

9. flash_standalone { file, reset: "hard", run: true } with no session open.

10. Negative test: open a session, then call flash_standalone on the same serial → expect DEVICE_BUSY.

Note: debug_connect halts the target's CPU. Don't attach to a board that's actively driving actuators/outputs in a way where an unplanned halt would be unsafe, without first confirming that's OK.