stm32-mcp

MCP-сервер, который позволяет Claude Code собирать, прошивать и общаться с оборудованием STM32.

stm32-mcp довольно специфичен для моего подхода к разработке железа, но, вероятно, будет полезен и другим! Его можно адаптировать под множество рабочих процессов, но он сфокусирован именно на моём (stlink-v3 mini, VCP на этом разъёме, микроконтроллер STM32).

Вы можете делать такие вещи:

я: эй, кто сейчас подключён?

claude: два безымянных пробника подключены к двум безымянным платам

я: ок, спроси их, кто они, и дай им прозвища на основе их ответа

claude: понял, хотите также дать прозвища пробникам? ваши платы — «дверной звонок A» и «синтезатор B»

я: да, я пометил эти пробники краской. назови звонок «синим», а синт — «красным»

claude: готово. что дальше?

я: дай им обоим VCP-команды, чтобы они могли общаться друг с другом, а затем пусть дверной звонок пригласит синт на свидание

claude: думает... готово, синт отказался. в море полно рыбы, дверной звонок!

MCP (Model Context Protocol) — это открытый стандарт, который позволяет ИИ-ассистентам вроде Claude использовать внешние инструменты. Этот сервер даёт Claude возможность компилировать вашу прошивку, прошивать её на плату, общаться с ней по последовательному порту и читать память через SWD. Он гибкий и разговорный.

[!WARNING] Этот сервер даёт ИИ прямой доступ к вашему компилятору, отладочному пробнику и последовательным портам. Он может прошивать прошивку, перезаписывать память и отправлять произвольные данные на ваше оборудование. Это мощно и полезно, но это не песочница. Знайте, что подключено, прежде чем позволить ему действовать.

Предварительные требования

• STM32CubeIDE установлен в /Applications/STM32CubeIDE.app (macOS) или /opt/st/stm32cubeide_* (Linux)

• Python 3.10+

• OpenOCD (brew install open-ocd) — для прошивки, чтения/записи памяти и живого мониторинга

• инструменты stlink с открытым исходным кодом (brew install stlink) — для перечисления пробников

• ST-Link подключён через USB (для прошивки/информации о плате)

• Последовательный порт доступен (ST-Link VCP или USB-UART адаптер)

Related MCP server: jlink-mcp

Установка

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

Регистрация в Claude Code

Вариант A: CLI

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

Вариант B: Конфигурация проекта

Добавьте в .claude/settings.json или .claude.json вашего проекта:

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

Самодостаточный CLI

В bin/ находятся четыре тонкие обёртки над тем же кодом, что используют инструменты MCP

Добавьте bin/ в ваш PATH:

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

Прозвища пробников и прозвища плат разрешаются.

Сборки используют ту же блокировку рабочего пространства headless CubeIDE, что и MCP, поэтому stm32-build/stm32-bf, соревнующиеся с управляемой агентом сборкой, будут ожидать в очереди.

Доступные инструменты

Сборка и прошивка

Управление несколькими платами

Прозвища плат следуют за физическим MCU (сохраняются при замене пробников). Прозвища пробников следуют за оборудованием ST-Link. Используйте прозвища в любом параметре probe во всех инструментах.

Последовательная связь

Отладка и мониторинг

Аппаратные последовательности

serial_sequence планирует несколько шагов (отправка по последовательному порту, задержка, захват с веб-камеры и чтение/запись памяти через SWD) за один вызов инструмента. Задержки используют time.sleep() в потоке исполнителя. Claude не может надёжно таймировать отдельные вызовы инструментов, поэтому это позволяет точно синхронизировать команды и ожидания.

Типы шагов

[
  { "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, to, expect?, read_timeout?, line_ending?} — to — это путь порта из serial_connect

• Шаг задержки: {delay_ms} — реальный time.sleep(), а не циклы вызовов инструментов

• Шаг захвата: {capture: true, label?, device_index?} — PNG сохраняется в /tmp/stm32-captures/

• Шаг записи памяти: {mem_write: true, address | symbol + elf_path, value, probe, width?}

• Шаг чтения памяти: {mem_read: true, address | symbol + elf_path, probe, count?, width?, label?}

Примечания к шагам памяти:

• probe принимает SN ST-Link, прозвище пробника или прозвище платы

• address — шестнадцатеричный (например, "0x48000418"); альтернативно используйте symbol + elf_path для разрешения по имени

• width — 8/16/32 бита, по умолчанию 32 (автоматически определяется из размера символа при использовании symbol)

• Каждая операция с памятью в настоящее время запускает новый процесс OpenOCD (накладные расходы ~десятки мс на операцию), поэтому межоперационная синхронизация ниже ~50 мс приблизительна. Сами задержки точны.

Параметры

• on_failure: "continue" (по умолчанию) выполняет все шаги независимо. "stop" прерывает при первой ошибке.

• filter_responses: Если true, шаблоны expect сопоставляются только со строками ответов VCP с префиксом > (игнорирует отладочный шум).

Вывод

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

Живой мониторинг памяти

Мониторинг переменных прошивки в реальном времени через SWD, без изменения прошивки или использования последовательного порта. OpenOCD работает как постоянный подпроцесс и опрашивает переменные через встроенный TCL-сокет.

Запуск сеанса

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
)

Переменные могут быть:

• Имена символов (строки): "blink" — разрешаются из ELF через arm-none-eabi-nm

• Словари с символом и типом: {"symbol": "temperature", "type": "float"} — интерпретирует 32-битное значение как IEEE 754

• Словари с сырым адресом: {"address": "0x20000304", "name": "x", "width": 32}

Чтение последних значений

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

Возвращает последние записи из кольцевого буфера в памяти (максимум 100 записей). Полная история записывается в выходной файл JSONL.

Формат вывода JSONL

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

Остановка сеанса

live_memory_stop(session_id="abc123")

Возвращает статистику: длительность, количество чтений, количество ошибок, путь к выходному файлу.

Ограничения

• Один сеанс на пробник — это аппаратное ограничение (одиночное SWD-соединение)

• Остановите перед прошивкой — live_memory удерживает SWD-соединение; stm32_flash и stm32_read/write_memory завершатся ошибкой, если сеанс активен

• Порт TCL 6666 — по умолчанию для OpenOCD. Остановите другие экземпляры OpenOCD, если есть конфликт

Последовательные настройки по умолчанию

• Скорость передачи: 115200

• Конец строки: LF (\n)

• Опрос чтения: 50 мс пауза между байтами, 200 мс пауза тишины

• Лимиты буфера: максимум 4096 байт на чтение

Разработка

MCP Inspector

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

Тестирование с замыканием

Последовательные инструменты можно тестировать без оборудования, используя loopback 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'