stm32-mcp

Claude Code が STM32 ハードウェアのビルド、フラッシュ、通信を行えるようにする MCP サーバーです。

stm32-mcp は、私がハードウェア開発に取り組む方法にかなり特化していますが、他の人にも役立つ可能性が高いです！ 多くのワークフローに合わせて調整できますが、これは私のワークフロー（stlink-v3 mini、そのヘッダー上の VCP、STM32 マイクロコントローラ）に焦点を絞っています。

次のようなことができます。

私: ねえ、今誰が接続されてる？

claude: 名前のない2つのプローブが、名前のない2つのPCBに接続されています

私: わかった、彼らに自分が誰か聞いて、その応答に基づいてニックネームを付けて

claude: 了解しました。プローブにもニックネームを付けますか？ あなたのボードは「doorbell A」と「synthesizer 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 は、1回のツール呼び出しで複数のステップ（シリアル送信、遅延、ウェブカメラキャプチャ、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 プロセスを起動します（操作ごとに数十ミリ秒のオーバーヘッド）。したがって、メモリ操作間のタイミングは約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" — 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")

統計（期間、読み取り回数、エラー回数、出力ファイルパス）を返します。

制約

• プローブごとに1セッション — これはハードウェアの制約です（単一の 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'