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.

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)

Related MCP server: Serial MCP Server

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

Multi-Board Management

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

Debug & Monitoring

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'