OpenOCD Debugger

OpenOCD MCP サーバー

AI アシスタントから直接マイクロコントローラーをデバッグできます。これはOpenOCDを操作するMCP サーバーです。MCP 互換の AI であれば、ファームウェアの書き込み、実行制御、実行中のターゲットの調査ができ、変数や周辺機器レジスターを生のアドレスではなく名前で読み取れます。

説明

デバッグプローブ（ST-Link、J-Link、CMSIS-DAP など）を介してターゲットに接続すると、 AI アシスタントで次の操作ができます。

• ファームウェアの書き込み — .elf／.bin／.hex イメージの書き込みと検証
• 実行制御 — 停止、再開、シングルステップ、リセット
• 状態の調査 — CPU レジスターとメモリーの読み書き
• ブレークポイントの設定 — ハードウェアおよびソフトウェアのブレークポイント。条件付きブレークポイント（式が真の場合のみ停止）やヒット回数ブレークポイントも設定できます
• メモリーの監視 — アドレスへの読み取り／書き込み／アクセス時に停止するハードウェアウォッチポイント
• 名前による変数の読み取り — ファームウェアの .elf シンボルから読み取ります（例：read_variable uart_rx_count）
• 変数のライブ監視 — CPU を停止せずに変数を一定時間サンプリングする機能です。DWARF から型（符号付き整数／浮動小数点数／ポインター／列挙型）を自動判別し、構造体／配列を展開できます
• 名前による周辺機器レジスターの読み取り — CMSIS-SVD ファイルから読み取り、名前付きビットフィールドにデコードします（例：RCC.CR、GPIOA.MODER）
• 安全対策 — エージェントが予期せずターゲットを損傷しないよう、権限レイヤー（読み取り専用モード、許可制のフラッシュ消去、フラッシュのパス／サイズ制限）を備えています

このサーバーはチップに依存しません。OpenOCD がサポートするすべてのターゲットで動作します。チップの設定と、必要に応じて SVD／ELF を指定してください。また、OpenOCD を自動で起動し、お使いのプラットフォーム用の OpenOCD を自動でダウンロードすることもできるため、手動で追加インストールする必要はありません。

対応 AI クライアント

MCP 互換のクライアントであれば動作します。以下のクライアントで動作確認済みです。

インストール

前提条件： Python 3.10 以降、およびターゲットに接続されたデバッグプローブ。

リポジトリをクローンし、仮想環境にパッケージをインストールします。

git clone https://github.com/microhenrio/openocd-mcp
cd openocd-mcp
python -m venv .venv

インストールすると、openocd-mcp コマンドが作成されます。

# Windows
.venv\Scripts\python -m pip install -e .

# macOS / Linux
.venv/bin/python -m pip install -e .

Windows のショートカット： setup.bat を実行すると、環境の作成、パッケージのインストール、Claude Code への自動登録が行われます。

OpenOCD は自動で取得されます。初回接続時に、お使いの OS／アーキテクチャ用のビルドがダウンロードされ、キャッシュされます（チェックサム検証済み）。openocd-mcp install-openocd で事前に取得することも、OPENOCD_BIN 環境変数を設定して既存のインストールを使用することもできます。

AI クライアントへの登録

サーバーの実行ファイルは次のとおりです。

# Windows
<repo>\.venv\Scripts\openocd-mcp.exe

# macOS / Linux
<repo>/.venv/bin/openocd-mcp

# Windows
claude mcp add --scope user openocd -- "%CD%\.venv\Scripts\openocd-mcp.exe"

# macOS / Linux
claude mcp add --scope user openocd -- "$PWD/.venv/bin/openocd-mcp"

{
  "mcpServers": {
    "openocd": {
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

{
  "mcpServers": {
    "openocd": {
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

{
  "mcpServers": {
    "openocd": {
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

{
  "openocd": {
    "command": "/path/to/.venv/bin/openocd-mcp"
  }
}

{
  "mcpServers": [
    {
      "name": "openocd",
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  ]
}

{
  "servers": {
    "openocd": {
      "type": "stdio",
      "command": "/path/to/.venv/bin/openocd-mcp"
    }
  }
}

更新

MCP 経由で公開されているセルフアップデートツールはありません。更新するには、ターミナルでコマンドを実行します。自分で実行するか、シェルにアクセスできる AI（例：Claude Code）に依頼してください。更新後は、新しいサーバーを読み込ませるため、AI クライアントを再起動してください。更新中だった場合、再インストールを妨げるファイルロックが発生することがあるため、先に古い openocd-mcp プロセスを停止する必要がある場合があります。

PyPI からのインストール（pip install openocd-mcp または uvx）：

pip install -U openocd-mcp

# uvx caches by default — force a refresh:
uvx --refresh openocd-mcp

Git クローンを編集可能モードでインストール（setup.bat またはこのリポジトリの手順で設定される方法）：

git pull
# only needed if dependencies changed:
.venv/bin/python -m pip install -e .   # or .venv\Scripts\python on Windows

pip show openocd-mcp でインストール済みのバージョンを確認できます。

使い方

1. チップを指定する

各ファームウェアプロジェクトで、デバッグ対象をサーバーに指定します。プロジェクトのルートに openocd-mcp.json を作成します（テンプレートは openocd-mcp.example.json にあります）。

{
  "target_cfg": "target/stm32g0x.cfg",
  "svd_file": "path/to/STM32G0B0.svd",
  "elf_file": "path/to/build/firmware.elf"
}

• target_cfg / interface_cfg — OpenOCD の設定ファイル（OpenOCD のスクリプトディレクトリからの相対パス）。デフォルトでは ST-Link プローブを使用します。使用するチップに合わせて target_cfg を設定してください。
• transport — "swd" または "jtag"。Cortex-M で J-Link を使用する場合は "swd" に設定します（interface_cfg: "interface/jlink.cfg"）。ST-Link の場合は空のままにします。
• svd_file — チップ用の CMSIS-SVD ファイル（周辺機器のレジスタを名前で指定できるようになります）。
• elf_file — ファームウェアのビルド出力（変数を名前で指定できるようになります）。

Windows での J-Link： OpenOCD は libusb 経由で J-Link に接続するため、Zadig を一度使って、J-Link のデバッグインターフェースを libusbK（または WinUSB）に割り当ててください（Interface 2 / MI_02）。新しい SEGGER ソフトウェア（v7.x 以降）は libusbK と互換性があるため、OpenOCD と SEGGER ツールを共存させられます。この手順は ST-Link では不要です。

または、使用しているチップを AI に伝えるだけで、セッションが自動的に設定されます。show_config を実行すれば、いつでも現在の設定を確認できます。

2. やりたいことを説明する

ボードを接続した状態で、やりたいことを説明します。AI が適切なツールを選びます。

ツール名を指定して呼び出す必要はありません。目的を説明すれば、AI が対応するツールに割り当てます。

3. 条件付きブレークポイントとウォッチポイント

条件付きブレークポイントは、条件が成立したときだけ停止します。常に実行されているコードの中から、特定のケースを捕捉するのに便利です。条件には TCL 式を使用し、次の 2 つのヘルパーを使えます。

• get_reg <name> — CPU レジスターの値（例：get_reg r0、get_reg pc）
• get_mem <addr> [width] — メモリーの値（例：get_mem 0x20000000）

意図を説明するだけで、AI が条件を作成します。

条件が偽の場合、サーバーは自動的に再開し、条件が真になるか、ユーザーが停止するまで実行を続けます。

ウォッチポイントは、メモリー位置へのアクセスが発生すると CPU を停止します。変数の値を破損させている原因を見つけるのに最適です。

• "0x20000000 への書き込みを監視する"
• "0x20000010 のアドレスへの読み取りまたは書き込みを監視する"

変数のライブ監視

CPUを停止せずに変数を監視する方法は2つあります。AIが実行できる方法と、自分で実行する方法です。

値の経時変化を手軽に、回数を指定して確認するには、AIに頼んでください。「tick_countを10サンプル監視して」「sensor_valueを200msごとに2秒間サンプリングして」のように指示します。watch_variablesツールが直接呼び出されるため、ELFを読み込んでおけば追加の設定は不要です。

特に構造体や配列を、期間を決めずにライブ表示するには、GUIを自分で実行してください。これはOpenOCDへの独自の接続を開くスタンドアロンアプリなので、同じターゲットを操作するAIセッションと並行して問題なく動作します。ただし、MCPツールではないため、AIから起動することはできません。直接実行してください。

openocd-watch tick_count sensor_value --elf path/to/firmware.elf
# or, if elf_file is set in openocd-mcp.json:
openocd-watch tick_count sensor_value

CPUを停止せずに変数をサンプリングし、ウィンドウ内のツリーを更新します。入力欄に項目を追加し（EnterキーまたはAddを押す）、選択した行をRemove（またはDeleteキー）で削除します。各項目は自動的に解決され、次のいずれかを指定できます。

• 変数名（uwTick、commsService）→ ELF内で検索されます。構造体、共用体、配列の場合は展開用の三角アイコンが表示され、メンバーや要素はDWARFの型情報から自動的に型判定されます（符号付き、浮動小数点、ポインター、列挙型、ビットフィールド、ネストされた構造体）。列挙型はシンボル名（STATE_HEATING (1)）を表示し、Cのビットフィールドはストレージワード全体ではなく、それぞれのビットのみを表示します。
• サイズを省略可能な16進アドレス（0x20000000、0x20000000:2）→ 直接読み取ります。

Formatのドロップダウンで値の表示形式（Auto (by C type) / Hex / Decimal / Signed / Float (f32) / Binary）を切り替えると、すぐに再描画されます。ポーリング間隔の変更には--interval、初期形式の指定には--format、ヘッドレスでの出力には--samples Nを使用します。Tkinter（標準のPythonに同梱）と、型情報を得るためのデバッグビルド（-g）が必要です。

OpenOCDがすでに起動していない場合は、--autostartを追加するとウィンドウがOpenOCDを起動し、終了時に停止します。AIクライアントも.batも不要で、完全にスタンドアロンで動作します。

openocd-watch uwTick xTickCount --elf path/to/firmware.elf --autostart --target target/stm32g0x.cfg

CPUコアレジスター（r0、pc、sp、…）を読み取るにはターゲットを停止する必要があります。必要な場合、AIが先に停止します。メモリ、変数、周辺機器レジスターはメモリマップされているため、CPUの実行中にも読み取れます（ライブ監視ウィンドウと同様です）。セッションで最初にconnectすると、OpenOCDが自動的に起動します。

安全性／権限

エージェントが予期せず対象に損害を与えないよう、変更を伴う操作には制限がかかります。 読み取りは常に許可されます。制限の対象は書き込み、フラッシュ書き込み、消去、および 生コマンドの抜け道です。

設定方法は3つあります（後から設定したものが優先されます）。

1. openocd-mcp.json 内の permissions オブジェクト（openocd-mcp.example.json を参照）。
2. 実行時の set_permissions ツール — たとえば、AI に「対象を読み取り専用にして」や 「このセッションではフラッシュ消去を許可して」と依頼します。
3. OPENOCD_MCP_READONLY=1 環境変数（読み取り専用を強制します）。

ブロックされた呼び出しは、どの権限を有効にすればよいかを説明する明確な BLOCKED: … メッセージを返します。show_config には有効な権限が表示されます。