STM32-MCP Server

Access STM32CubeIDE and debug tools

Documentation

stm32-mcp

MCP server that lets Claude Code build, flash, and communicate with STM32 hardware.

stm32-mcp is pretty specific to how I tend to approach hardware development, but it is likely useful to others, too! It could be massaged to fit lots of workflows, but this is laser focused on mine (stlink-v3 mini, VCP on that header, STM32 microcontroller).

You can do things like:

me: hey who is plugged in right now?

claude: two unnamed probes connected to two unnamed PCBs

me: k ask them who they are and give them a nickname based on their response

claude: got it, do you want to nickname the probes too? your boards are 'doorbell A' and 'synthesizer B'

me: yep, I put paint marker on those probes. call doorbell's 'blue' and the synth's 'red'

claude: done. what's next?

me: give them both VCP commands so they can talk to each other, then have the doorbell ask the synth on a date

claude: thinking... done, synth declined. plenty of fish in the sea, doorbell!

MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude use external tools. This server gives Claude the ability to compile your firmware, flash it to a board, talk to it over serial, and read memory via SWD. It is flexible and conversational.

[!WARNING] This server gives an AI direct access to your compiler, debug probe, and serial ports. It can flash firmware, overwrite memory, and send arbitrary data to your hardware. This is powerful and useful, but it is not a sandbox. Know what's connected before you let it rip.

Prerequisites

STM32CubeIDE installed at /Applications/STM32CubeIDE.app (macOS) or /opt/st/stm32cubeide_* (Linux)
Python 3.10+
OpenOCD (brew install open-ocd) — for flash, memory read/write, and live monitoring
open-source stlink tools (brew install stlink) — for probe enumeration
ST-Link connected via USB (for flash/board info)
Serial port available (ST-Link VCP or USB-UART adapter)

Installation

git clone https://github.com/shieldyguy/stm32-mcp.git
cd stm32-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Register with Claude Code

Option A: CLI

claude mcp add stm32 -- /path/to/stm32-mcp/.venv/bin/python -m stm32_mcp.server

Option B: Project config

Add to your project's .claude/settings.json or .claude.json:

{
  "mcpServers": {
    "stm32": {
      "command": "/path/to/stm32-mcp/.venv/bin/python",
      "args": ["-m", "stm32_mcp.server"]
    }
  }
}

Available Tools

Build & Flash

Tool	Description
`stm32_build`	Compile firmware using CubeIDE headless builder
`stm32_flash`	Flash .elf/.bin/.hex to board via ST-Link SWD
`stm32_build_and_flash`	Build + flash in one step (the 90% case)
`stm32_board_info`	Read ST-Link/MCU info (device ID, flash size, voltage)

Multi-Board Management

Tool	Description
`stm32_list_probes`	Show all connected boards with nicknames and MCU IDs
`stm32_set_nickname`	Name a board (by MCU UID) or probe (by ST-Link SN)

Board nicknames follow the physical MCU (persist across probe swaps). Probe nicknames follow the ST-Link hardware. Use nicknames in any probe parameter across all tools.

Serial Communication

Tool	Description
`serial_list_ports`	List serial ports (marks ST-Link VCP ports with nicknames)
`serial_connect`	Open a serial connection
`serial_send`	Send data and read response
`serial_read`	Read buffered serial data
`serial_disconnect`	Close a serial connection
`serial_sequence`	Run multi-step send/delay/memory sequences in one call

Debug & Monitoring

Tool	Description
`stm32_read_memory`	Read memory by address or variable name (from ELF symbols)
`stm32_write_memory`	Write memory by address or variable name
`live_memory_start`	Start continuous background memory monitoring via SWD
`live_memory_read`	Read recent entries from a live memory session
`live_memory_stop`	Stop a live memory session

Hardware Sequences

serial_sequence runs multiple steps — serial send, delay, webcam capture, and SWD memory read/write — in a single tool call with real timing between steps. No tool-call overhead between steps; delays use a real time.sleep() in the executor thread. This is critical for timing-sensitive hardware test sequences and for bit-banging registers over SWD (e.g. blinking a GPIO on a board with no firmware).

Step types

[
  { "send": "SIM_LEFT", "to": "/dev/cu.usbmodem11202" },
  { "delay_ms": 500 },
  {
    "send": "GET_BLINK_STATE",
    "to": "/dev/cu.usbmodem11402",
    "expect": "BLINK"
  },
  { "capture": true, "label": "post_brake" },
  {
    "mem_write": true,
    "address": "0x48000418",
    "value": "0x40",
    "probe": "yellow"
  },
  { "delay_ms": 1000 },
  {
    "mem_read": true,
    "address": "0x48000400",
    "count": 2,
    "probe": "yellow",
    "label": "gpio_post"
  }
]

Send step: {send, to, expect?, read_timeout?, line_ending?} — to is the port path from serial_connect
Delay step: {delay_ms} — real time.sleep(), not tool-call round-trips
Capture step: {capture: true, label?, device_index?} — PNG saved to /tmp/stm32-captures/
Memory write step: {mem_write: true, address | symbol + elf_path, value, probe, width?}
Memory read step: {mem_read: true, address | symbol + elf_path, probe, count?, width?, label?}

Memory step notes:

probe accepts ST-Link SN, probe nickname, or board nickname
address is hex (e.g. "0x48000418"); alternatively use symbol + elf_path to resolve by name
width is 8/16/32 bits, defaults to 32 (auto-detected from symbol size when using symbol)
Each memory op currently launches a fresh OpenOCD process (~tens of ms overhead per op), so inter-memory-op timing below ~50ms is approximate. Delays themselves are accurate.

Parameters

on_failure: "continue" (default) runs all steps regardless. "stop" aborts on first failure.
filter_responses: When true, expect patterns match only >-prefixed VCP response lines (ignores debug noise).

Output

Step 1 [/dev/cu.usbmodem11202] SEND: SIM_LEFT
  Response: >OK:SIM_LEFT

Step 2 DELAY: 500ms

Step 3 [/dev/cu.usbmodem11402] SEND: GET_BLINK_STATE
  Response: >BLINK_STATE:BLINK
  Expect "BLINK": PASS

Step 4 [yellow] MEM_WRITE: Wrote 0x00000040 to 0x48000418

Step 5 DELAY: 1000ms

Step 6 [yellow] MEM_READ: gpio_post 0x48000400: 0xabffdfff 0x00000080

Summary: 2/2 sends OK, 1/1 assertions PASS, 1/1 mem_writes OK, 1/1 mem_reads OK

Live Memory Monitoring

Monitor firmware variables in real time via SWD, without modifying firmware or using serial. OpenOCD runs as a persistent subprocess and polls variables over its built-in TCL socket.

Start a session

live_memory_start(
    variables='["blink", "ts"]',       # symbol names from ELF
    elf_path="/path/to/firmware.elf",
    probe="taillight",                  # board/probe nickname
    interval_ms=500                     # min 250ms
)

Variables can be:

Symbol names (strings): "blink" — resolved from the ELF via arm-none-eabi-nm
Dicts with symbol + type: {"symbol": "temperature", "type": "float"} — interprets 32-bit value as IEEE 754
Dicts with raw address: {"address": "0x20000304", "name": "x", "width": 32}

Read recent values

live_memory_read(session_id="abc123", last_n=10)

Returns recent entries from an in-memory ring buffer (max 100 entries). Full history is written to the JSONL output file.

JSONL output format

{ "t": 1709830123.456, "elapsed_s": 1.002, "values": { "blink": 65539 } }

Stop a session

live_memory_stop(session_id="abc123")

Returns stats: duration, read count, error count, output file path.

Constraints

One session per probe — this is a hardware constraint (single SWD connection)
Stop before flashing — live_memory holds the SWD connection; stm32_flash and stm32_read/write_memory will fail if a session is active
TCL port 6666 — OpenOCD's default. Stop other OpenOCD instances first if there's a conflict

Serial Defaults

Baud rate: 115200
Line ending: LF (\n)
Read polling: 50ms inter-byte sleep, 200ms silence break
Buffer limits: 4096 bytes max read

Development

MCP Inspector

source .venv/bin/activate
mcp dev src/stm32_mcp/server.py

Loopback Testing

Serial tools can be tested without hardware using pyserial's loopback:

import serial
ser = serial.serial_for_url("loop://", baudrate=115200, timeout=0.1)
ser.write(b"PING\n")
print(ser.read(100))  # b'PING\n'