stm32-mcp

MCP-Server, der es Claude Code ermöglicht, STM32-Hardware zu bauen, zu flashen und mit ihr zu kommunizieren.

stm32-mcp ist ziemlich spezifisch für meinen Ansatz bei der Hardwareentwicklung, aber es könnte auch für andere nützlich sein! Es könnte an viele Workflows angepasst werden, aber es ist stark auf meinen fokussiert (stlink-v3 mini, VCP auf diesem Header, STM32-Mikrocontroller).

Du kannst zum Beispiel Folgendes tun:

ich: hey, wer ist gerade angeschlossen?

claude: zwei unbenannte Sonden, die mit zwei unbenannten PCBs verbunden sind

ich: ok, frag sie, wer sie sind, und gib ihnen einen Spitznamen basierend auf ihrer Antwort

claude: verstanden, möchtest du auch die Sonden benennen? deine Boards sind 'Türklingel A' und 'Synthesizer B'

ich: ja, ich habe Farbe auf diese Sonden gemacht. nenne die Türklingel 'blau' und den Synthesizer 'rot'

claude: erledigt. was als Nächstes?

ich: gib ihnen beiden VCP-Befehle, damit sie miteinander sprechen können, und lass dann die Türklingel den Synthesizer nach einem Date fragen

claude: denkt nach... erledigt, der Synthesizer hat abgelehnt. Es gibt viele Fische im Meer, Türklingel!

MCP (Model Context Protocol) ist ein offener Standard, der KI-Assistenten wie Claude die Nutzung externer Tools ermöglicht. Dieser Server gibt Claude die Fähigkeit, Ihre Firmware zu kompilieren, sie auf ein Board zu flashen, über seriell mit ihr zu sprechen und Speicher über SWD zu lesen. Er ist flexibel und gesprächig.

[!WARNING] Dieser Server gibt einer KI direkten Zugriff auf Ihren Compiler, Debug-Probe und serielle Ports. Er kann Firmware flashen, Speicher überschreiben und beliebige Daten an Ihre Hardware senden. Das ist mächtig und nützlich, aber es ist keine Sandbox. Wissen Sie, was angeschlossen ist, bevor Sie ihn loslassen.

Voraussetzungen

• STM32CubeIDE installiert unter /Applications/STM32CubeIDE.app (macOS) oder /opt/st/stm32cubeide_* (Linux)

• Python 3.10+

• OpenOCD (brew install open-ocd) — zum Flashen, Speicher lesen/schreiben und Live-Überwachung

• Open-Source-stlink-Tools (brew install stlink) — zur Sondenerkennung

• ST-Link über USB verbunden (für Flash/Board-Informationen)

• Serielle Schnittstelle verfügbar (ST-Link VCP oder USB-UART-Adapter)

Related MCP server: jlink-mcp

Installation

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

Bei Claude Code registrieren

Option A: CLI

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

Option B: Projektkonfiguration

Fügen Sie zu Ihrem Projekt .claude/settings.json oder .claude.json hinzu:

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

Self-Service-CLI

bin/ enthält vier dünne Wrapper über denselben Code, den die MCP-Tools verwenden

Fügen Sie bin/ zu Ihrem PATH hinzu:

export PATH="/path/to/stm32-mcp/bin:$PATH"

Sondenspitznamen und Board-Spitznamen werden aufgelöst.

Builds teilen sich die Headless-CubeIDE-Workspace-Sperre des MCP, sodass ein stm32-build/stm32-bf, das mit einem agentengesteuerten Build konkurriert, sich dahinter einreiht.

Verfügbare Tools

Build & Flash

Multi-Board-Verwaltung

Board-Spitznamen folgen dem physischen MCU (bleiben über Sondenwechsel hinweg erhalten). Sondenspitznamen folgen der ST-Link-Hardware. Verwenden Sie Spitznamen in jedem probe-Parameter in allen Tools.

Serielle Kommunikation

Debug & Überwachung

Hardware-Sequenzen

serial_sequence plant mehrere Schritte (serielles Senden, Verzögerung, Webcam-Erfassung und SWD-Speicher lesen/schreiben) in einem Tool-Aufruf. Verzögerungen verwenden ein time.sleep() im Executor-Thread. Claude kann einzelne Tool-Aufrufe nicht zuverlässig timen, daher ermöglicht dies eine enge zeitliche Abstimmung von Befehlen und Erwartungen.

Schritttypen

[
  { "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"
  }
]

• Sendeschritt: {send, to, expect?, read_timeout?, line_ending?} — to ist der Portpfad von serial_connect

• Verzögerungsschritt: {delay_ms} — echtes time.sleep(), keine Tool-Aufruf-Roundtrips

• Erfassungsschritt: {capture: true, label?, device_index?} — PNG wird unter /tmp/stm32-captures/ gespeichert

• Speicherschreibschritt: {mem_write: true, address | symbol + elf_path, value, probe, width?}

• Speicherleseschritt: {mem_read: true, address | symbol + elf_path, probe, count?, width?, label?}

Hinweise zu Speicherschritten:

• probe akzeptiert ST-Link-Seriennummer, Sondenspitznamen oder Board-Spitznamen

• address ist hexadezimal (z. B. "0x48000418"); alternativ verwenden Sie symbol + elf_path, um nach Namen aufzulösen

• width ist 8/16/32 Bit, Standard ist 32 (automatisch aus der Symbolgröße erkannt, wenn symbol verwendet wird)

• Jeder Speicheroperation startet derzeit einen frischen OpenOCD-Prozess (~zig ms Overhead pro Operation), daher ist die zeitliche Abstimmung zwischen Speicheroperationen unter ~50 ms ungefähr. Verzögerungen selbst sind genau.

Parameter

• on_failure: "continue" (Standard) führt alle Schritte unabhängig aus. "stop" bricht beim ersten Fehler ab.

• filter_responses: Wenn true, passen expect-Muster nur auf >-präfixierte VCP-Antwortzeilen (ignoriert Debug-Rauschen).

Ausgabe

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-Speicherüberwachung

Überwachen Sie Firmware-Variablen in Echtzeit über SWD, ohne die Firmware zu ändern oder seriell zu verwenden. OpenOCD läuft als persistenter Unterprozess und fragt Variablen über seinen eingebauten TCL-Socket ab.

Eine Sitzung starten

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
)

Variablen können sein:

• Symbolnamen (Zeichenketten): "blink" — aus dem ELF über arm-none-eabi-nm aufgelöst

• Dicts mit Symbol + Typ: {"symbol": "temperature", "type": "float"} — interpretiert 32-Bit-Wert als IEEE 754

• Dicts mit roher Adresse: {"address": "0x20000304", "name": "x", "width": 32}

Neueste Werte lesen

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

Gibt die neuesten Einträge aus einem In-Memory-Ringpuffer zurück (max. 100 Einträge). Die vollständige Historie wird in die JSONL-Ausgabedatei geschrieben.

JSONL-Ausgabeformat

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

Eine Sitzung beenden

live_memory_stop(session_id="abc123")

Gibt Statistiken zurück: Dauer, Anzahl der Lesevorgänge, Anzahl der Fehler, Pfad der Ausgabedatei.

Einschränkungen

• Eine Sitzung pro Sonde — dies ist eine Hardware-Einschränkung (einzelne SWD-Verbindung)

• Vor dem Flashen beenden — live_memory hält die SWD-Verbindung; stm32_flash und stm32_read/write_memory schlagen fehl, wenn eine Sitzung aktiv ist

• TCL-Port 6666 — Standard von OpenOCD. Beenden Sie zuerst andere OpenOCD-Instanzen, wenn es einen Konflikt gibt

Serielle Standardeinstellungen

• Baudrate: 115200

• Zeilenende: LF (\n)

• Lese-Polling: 50 ms Schlaf zwischen Bytes, 200 ms Stille-Pause

• Puffergrenzen: maximal 4096 Bytes lesen

Entwicklung

MCP-Inspektor

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

Loopback-Tests

Serielle Tools können ohne Hardware mit dem Loopback von pyserial getestet werden:

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'