stm32-mcp

Claude Code가 STM32 하드웨어를 빌드, 플래시, 통신할 수 있게 해주는 MCP 서버입니다.

stm32-mcp는 제가 하드웨어 개발에 접근하는 방식에 상당히 특화되어 있지만, 다른 사람들에게도 유용할 가능성이 높습니다! 다양한 워크플로우에 맞게 조정할 수 있지만, 이 프로젝트는 제 환경(stlink-v3 mini, 해당 헤더의 VCP, STM32 마이크로컨트롤러)에 초점을 맞추고 있습니다.

다음과 같은 작업을 할 수 있습니다:

나: 지금 누가 연결되어 있어?

claude: 이름 없는 프로브 두 개가 이름 없는 PCB 두 개에 연결되어 있습니다

나: 좋아, 그들에게 누구인지 물어보고 응답에 따라 별명을 지어줘

claude: 알겠습니다, 프로브에도 별명을 지어드릴까요? 보드는 '초인종 A'와 '신디사이저 B'입니다

나: 응, 그 프로브들에 페인트 마커로 표시해뒀어. 초인종 건 '파란색', 신디사이저 건 '빨간색'이라고 불러줘

claude: 완료했습니다. 다음은 무엇인가요?

나: 둘 다 서로 통신할 수 있게 VCP 명령을 주고, 초인종이 신디사이저에게 데이트를 신청하게 해줘

claude: 생각 중... 완료했습니다, 신디사이저가 거절했습니다. 바다에는 물고기가 많으니까요, 초인종!

MCP (Model Context Protocol)는 Claude와 같은 AI 어시스턴트가 외부 도구를 사용할 수 있게 해주는 개방형 표준입니다. 이 서버는 Claude에게 펌웨어 컴파일, 보드 플래시, 시리얼 통신, SWD를 통한 메모리 읽기 기능을 제공합니다. 유연하고 대화형입니다.

[!WARNING] 이 서버는 AI에게 컴파일러, 디버그 프로브, 시리얼 포트에 대한 직접적인 접근 권한을 부여합니다. 펌웨어를 플래시하고, 메모리를 덮어쓰고, 하드웨어에 임의의 데이터를 보낼 수 있습니다. 강력하고 유용하지만, 샌드박스가 아닙니다. 실행하기 전에 무엇이 연결되어 있는지 확인하세요.

사전 요구사항

• 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 도구가 사용하는 것과 동일한 코드에 대한 4개의 얇은 래퍼가 포함되어 있습니다

bin/을 PATH에 추가:

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

프로브 별명과 보드 별명이 해석됩니다.

빌드는 MCP의 헤드리스 CubeIDE 워크스페이스 잠금을 공유하므로, 에이전트 주도 빌드와 경쟁하는 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는 ST-Link SN, 프로브 별명 또는 보드 별명을 허용

• address는 16진수(예: "0x48000418"); 또는 symbol + elf_path를 사용하여 이름으로 해석

• width는 8/16/32비트, 기본값은 32 (symbol 사용 시 심볼 크기에서 자동 감지)

• 각 메모리 작업은 현재 새 OpenOCD 프로세스를 시작하므로(작업당 수십 ms 오버헤드), 메모리 작업 간 타이밍이 ~50ms 미만이면 근사치입니다. 지연 자체는 정확합니다.

매개변수

• 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" — arm-none-eabi-nm을 통해 ELF에서 해석

• 심볼 + 타입이 있는 딕셔너리: {"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)

• 읽기 폴링: 50ms 바이트 간 대기, 200ms 무음 중단

• 버퍼 제한: 최대 4096바이트 읽기

개발

MCP Inspector

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

루프백 테스트

시리얼 도구는 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'