stm32-mcp

Servidor MCP que permite a Claude Code compilar, flashear y comunicarse con hardware STM32.

stm32-mcp es bastante específico de cómo suelo abordar el desarrollo de hardware, ¡pero es probable que también sea útil para otros! Se podría adaptar para encajar en muchos flujos de trabajo, pero está centrado al máximo en el mío (stlink-v3 mini, VCP en ese conector, microcontrolador STM32).

Puedes hacer cosas como:

yo: oye, ¿quién está conectado ahora mismo?

claude: dos sondas sin nombre conectadas a dos PCB sin nombre

yo: vale, pregúntales quiénes son y ponles un apodo según su respuesta

claude: entendido, ¿quieres poner apodos también a las sondas? tus placas son 'timbre A' y 'sintetizador B'

yo: sí, les puse marcador de pintura a esas sondas. llama 'azul' a la del timbre y 'rojo' a la del sintetizador

claude: hecho. ¿qué sigue?

yo: dales a ambas comandos VCP para que puedan hablar entre sí, y luego haz que el timbre le pida una cita al sintetizador

claude: pensando... hecho, el sintetizador declinó. ¡hay más peces en el mar, timbre!

MCP (Model Context Protocol) es un estándar abierto que permite a asistentes de IA como Claude usar herramientas externas. Este servidor le da a Claude la capacidad de compilar tu firmware, flashearlo en una placa, hablar con ella por serie y leer memoria vía SWD. Es flexible y conversacional.

[!WARNING] Este servidor da a una IA acceso directo a tu compilador, sonda de depuración y puertos serie. Puede flashear firmware, sobrescribir memoria y enviar datos arbitrarios a tu hardware. Es potente y útil, pero no es un sandbox. Sabe qué está conectado antes de darle rienda suelta.

Requisitos previos

• STM32CubeIDE instalado en /Applications/STM32CubeIDE.app (macOS) o /opt/st/stm32cubeide_* (Linux)

• Python 3.10+

• OpenOCD (brew install open-ocd) — para flasheo, lectura/escritura de memoria y monitorización en vivo

• herramientas stlink de código abierto (brew install stlink) — para la enumeración de sondas

• ST-Link conectado vía USB (para información de flasheo/placa)

• Puerto serie disponible (VCP de ST-Link o adaptador USB-UART)

Related MCP server: jlink-mcp

Instalación

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

Registrar con Claude Code

Opción A: CLI

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

Opción B: Configuración del proyecto

Añade a .claude/settings.json o .claude.json de tu proyecto:

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

CLI de autoservicio

bin/ contiene cuatro envoltorios finos sobre el mismo código que usan las herramientas MCP

Añade bin/ a tu PATH:

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

Los apodos de sondas y de placas se resuelven.

Las compilaciones comparten el bloqueo del espacio de trabajo headless de CubeIDE del MCP, por lo que un stm32-build/stm32-bf que compita con una compilación impulsada por un agente se pondrá en cola detrás de ella.

Herramientas disponibles

Compilar y flashear

Gestión de múltiples placas

Los apodos de placa siguen al MCU físico (persisten al cambiar de sonda). Los apodos de sonda siguen al hardware ST-Link. Usa apodos en cualquier parámetro probe de todas las herramientas.

Comunicación serie

Depuración y monitorización

Secuencias de hardware

serial_sequence programa varios pasos (envío serie, retardo, captura de webcam y lectura/escritura de memoria SWD) en una sola llamada de herramienta. Los retardos usan un time.sleep() en el hilo ejecutor. Claude no puede cronometrar de forma fiable llamadas individuales a herramientas, por lo que esto permite un control preciso del tiempo de los comandos y las expectativas.

Tipos de paso

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

• Paso de envío: {send, to, expect?, read_timeout?, line_ending?} — to es la ruta del puerto de serial_connect

• Paso de retardo: {delay_ms} — time.sleep() real, no idas y vueltas de llamadas a herramientas

• Paso de captura: {capture: true, label?, device_index?} — PNG guardado en /tmp/stm32-captures/

• Paso de escritura de memoria: {mem_write: true, address | symbol + elf_path, value, probe, width?}

• Paso de lectura de memoria: {mem_read: true, address | symbol + elf_path, probe, count?, width?, label?}

Notas sobre los pasos de memoria:

• probe acepta SN de ST-Link, apodo de sonda o apodo de placa

• address es hexadecimal (p. ej. "0x48000418"); alternativamente usa symbol + elf_path para resolver por nombre

• width es de 8/16/32 bits, por defecto 32 (se detecta automáticamente a partir del tamaño del símbolo cuando se usa symbol)

• Cada operación de memoria lanza actualmente un proceso OpenOCD nuevo (sobrecarga de ~decenas de ms por operación), por lo que el tiempo entre operaciones de memoria por debajo de ~50ms es aproximado. Los retardos en sí son precisos.

Parámetros

• on_failure: "continue" (por defecto) ejecuta todos los pasos sin importar nada. "stop" aborta ante el primer fallo.

• filter_responses: Cuando es true, los patrones de expect solo coinciden con líneas de respuesta VCP prefijadas con > (ignora el ruido de depuración).

Salida

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

Monitorización de memoria en vivo

Monitorea variables de firmware en tiempo real vía SWD, sin modificar el firmware ni usar serie. OpenOCD se ejecuta como un subproceso persistente y consulta las variables a través de su socket TCL integrado.

Iniciar una sesión

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
)

Las variables pueden ser:

• Nombres de símbolo (cadenas): "blink" — resueltos desde el ELF mediante arm-none-eabi-nm

• Diccionarios con símbolo + tipo: {"symbol": "temperature", "type": "float"} — interpreta el valor de 32 bits como IEEE 754

• Diccionarios con dirección cruda: {"address": "0x20000304", "name": "x", "width": 32}

Leer valores recientes

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

Devuelve las entradas recientes de un búfer circular en memoria (máximo 100 entradas). El historial completo se escribe en el archivo de salida JSONL.

Formato de salida JSONL

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

Detener una sesión

live_memory_stop(session_id="abc123")

Devuelve estadísticas: duración, número de lecturas, número de errores, ruta del archivo de salida.

Restricciones

• Una sesión por sonda — esto es una restricción de hardware (una única conexión SWD)

• Detener antes de flashear — live_memory mantiene la conexión SWD; stm32_flash y stm32_read/write_memory fallarán si hay una sesión activa

• Puerto TCL 6666 — el predeterminado de OpenOCD. Detén antes otras instancias de OpenOCD si hay un conflicto

Valores predeterminados de serie

• Velocidad en baudios: 115200

• Fin de línea: LF (\n)

• Sondeo de lectura: 50ms de espera entre bytes, corte tras 200ms de silencio

• Límites de búfer: 4096 bytes máximos de lectura

Desarrollo

MCP Inspector

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

Pruebas de loopback

Las herramientas serie se pueden probar sin hardware usando el loopback de pyserial:

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'