MiSTerClaw

👾🦀 MiSTerClaw — MiSTer-FPGA用MCPリモートコントロール

MiSTerClawは、MiSTer-FPGA向けの初めてのMCPサーバーです。あらゆるAIエージェントからMiSTerを操作できます。

（バッジの提案：ありがとうございます、punkpeye。）

v0.8.1では、検証済みのネイティブZIPメンバー起動機能と、独立したGBA2Pプロファイルが追加されました。ダウンロードとチェックサムについては、リリースノートとハードウェアテストの制限、ZIPメンバーの使用方法、およびGitHub Releasesをご覧ください。

これは何ですか？

MiSTerClawを使うと、Claude、ChatGPT、OpenClaw、Hermes、CursorなどのAIエージェントから、ネットワーク経由でMiSTer-FPGAを操作できます。ゲームの起動、ROMライブラリの検索、スクリーンショットの撮影、コア設定やDIPスイッチの読み取りと変更、conf_strベースの位置計算によるOSDメニューの操作（実験的な機能で、すべてのコアで安定して動作するわけではありません）、詳細なシステム情報の照会、システムの管理ができるほか、どこからでも安全にリモートアクセスできるようTailscale VPNを設定することもできます。フロッピーディスクコア（PC8801、MSXなど）は、ゲームをシームレスに読み込むためのPostLaunch自動リセットに対応しています。Model Context Protocol (MCP)標準を使用しているため、MCP対応クライアントならすぐに利用できます。MCPに対応していないエージェント向けに、CLIクライアントも含まれています。

アーケードゲーム

アーケードゲームは.mra記述子からインデックス化され、直接起動できます（初期対応にご協力いただいたsttに感謝します）。MAME ZIPフォルダーやシステム全体で単一のRBFとしては扱われません。SDとUSBでは、再帰的な正規フォルダーおよび_alternativesに対応しています。同じルートに正規の記述子がある場合、生成された_Organizedビューは除外されます。_Organizedのみのコレクションはフォールバックとして引き続き使用できます。バイト単位で同一のフォールバック記述子は重複排除されますが、異なるバリアントは保持されます。件数は、ユニークなゲームシリーズではなく、インデックス化された記述子／バリアントを示します。キャッシュスキーマv3では、無関係なキャッシュ済みシステムを保持したまま、古いv1/v2のアーケードおよびMAMEエントリーをその場でアップグレードします。アップグレード時にROM全体を再スキャンする必要はありません。

場所を指定したSDの再スキャンでは、_Arcadeも更新されます。また、既存のSD／USBアーケードフォルダーは置き換えずに統合されます。場所を指定した再スキャンは、すぐにstatus: pendingを返すようになりました。systems.scanningがfalseになるまでポーリングしてください。更新中も既存の結果は引き続き利用できます。重複するスキャン要求や無効な場所は、明示的に失敗します。MRAの起動時にはファイルを検証し、仮想入力デバイスを再作成して、記述子で要求された<rbf>をcore_nameで返します。この応答だけでは、FPGAの読み込み完了は確認できません。

MCPのセットアップ

MCPクライアントの設定にMiSTerClawを追加します。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "misterclaw": {
      "command": "/path/to/misterclaw-mcp",
      "args": ["--host", "mister-fpga"]
    }
  }
}

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "misterclaw": {
      "command": "/path/to/misterclaw-mcp",
      "args": ["--host", "mister-fpga"]
    }
  }
}

MCP ツール

ツール	説明
mister_status	現在再生中の内容を表示します
mister_launch	検索またはパスを指定してゲームを起動します
mister_search	ROM ライブラリを検索します
mister_systems	ROM 数とともに、利用可能なシステムをすべて一覧表示します
mister_screenshot	スクリーンショットを撮影します（PNG 画像を返します）
mister_info	システム情報を表示します（ホスト名、IP、温度、RAM、ディスク、稼働時間）
mister_input	キーボード入力を送信します（OSD の操作、名前付きキー）
mister_osd_info	CONF_STR データベースから OSD メニュー構造を照会します
mister_osd_visible	現在の設定に基づき、表示されている OSD メニュー項目のみを表示します
mister_cfg_read	コア設定を読み取ります（オプションと DIP スイッチ）
mister_cfg_write	自動バックアップ付きでコア設定を変更します
mister_reload	設定変更を適用するため、現在のコアを再読み込みします
mister_osd_navigate	名前を指定して、特定の OSD メニュー項目に移動します
mister_system_info	システムの設定、メモ、OSD メニューを取得します
mister_rescan	ROM ライブラリを再スキャンします（特定のドライブを指定することもできます）
mister_tailscale	Tailscale VPN を管理します
mister_shell	シェルコマンドを実行します（初期の出力処理の修正に感謝します：stt）

会話例

設定が完了したら、エージェントに話しかけるだけです。

You: "What games do I have for SNES?"
Agent: You have 13,435 SNES ROMs! Here are some highlights...

You: "Launch Street Fighter 2"
Agent: 🎮 Launched Street Fighter II Turbo on SNES!

You: "Take a screenshot and show me"
Agent: [screenshot of the game running]

You: "What systems do I have?"
Agent: Your MiSTer has 70+ systems! Top ones:
  - SNES: 13,435 ROMs
  - C64: 46,736 ROMs
  - Amiga: 55,793 ROMs
  ...

You: "Set up Tailscale so I can reach the MiSTer from anywhere"
Agent: Installing Tailscale... Done!
       Please authenticate: https://login.tailscale.com/a/xxx
       After that your MiSTer is reachable from anywhere.

You: "What settings does R-Type have?"
Agent: R-Type (M72 core) has these settings:
       Core Options:
         - No Death Mode: Off
         - Service Mode: Off
       DIP Switches:
         - Difficulty: Medium
         - Coin A: 1 Coin / 1 Credit
         - Lives: 3
         - Demo Sounds: On
         - Continue: Yes

You: "Enable No Death Mode"
Agent: ⚙️ Set "No Death Mode" to On in R-Type.
       The core reloads automatically — change is live!

You: "Navigate to the Reset option in the OSD"
Agent: Navigated to Reset in the SNES core OSD.

You: "What do I need to know about the PC8801 system?"
Agent: PC8801 uses the PC8801 core with .d88 floppy disk images.
       Notes: After loading a disk, press F12 → Reset to boot.
       OSD Menu: FDD0, FDD1, Reset, CPU Speed, ...

CLI クライアント

OpenClaw、Codex、Claude Code など、シェルアクセスが可能なエージェントには、MCP より CLI クライアントのほうが効率的な場合があります。コンテキストにツールスキーマを含める必要がなく、必要なときに呼び出すだけです。シェルスクリプトや自動化にも便利です。

# Check what's playing
misterclaw-send -H mister-fpga status

# Search for games
misterclaw-send -H mister-fpga search "zelda" --limit 5
misterclaw-send -H mister-fpga search "sonic" --system MegaDrive

# Launch a game
misterclaw-send -H mister-fpga launch "super mario world" --system SNES

# List all systems with ROM counts
misterclaw-send -H mister-fpga systems

# Take a screenshot
misterclaw-send -H mister-fpga screenshot -o game.png

# System info (CPU, memory, storage, uptime)
misterclaw-send -H mister-fpga info

# Run shell commands — configure MiSTer.ini, run updates, manage files
misterclaw-send -H mister-fpga shell "cat /media/fat/MiSTer.ini"
misterclaw-send -H mister-fpga shell "/media/fat/Scripts/update_all.sh"

# Send keyboard input (OSD navigation)
misterclaw-send -H mister-fpga input key osd
misterclaw-send -H mister-fpga input combo leftalt f12

# Query OSD menu structure
misterclaw-send -H mister-fpga osd-info
misterclaw-send -H mister-fpga osd-info --core SNES

# Navigate to a specific OSD menu item
misterclaw-send -H mister-fpga osd-navigate Reset
misterclaw-send -H mister-fpga osd-navigate "Aspect ratio"

# Get detailed system info (config, notes, OSD menu)
misterclaw-send -H mister-fpga system-info PC8801
misterclaw-send -H mister-fpga system-info SNES

# Read core settings (options + DIP switches)
misterclaw-send -H mister-fpga cfg-read

# Modify settings
misterclaw-send -H mister-fpga cfg-write --option "Free Play" --value On

# Reload core to apply changes
misterclaw-send -H mister-fpga reload

# Rescan ROM library (after adding new games)
misterclaw-send -H mister-fpga rescan
misterclaw-send -H mister-fpga rescan --location usb0

# JSON output for scripting
misterclaw-send -H mister-fpga status --json
misterclaw-send -H mister-fpga systems --json

すべてのコマンドは、機械可読な出力を得るための --json に対応しています。

インストール

バイナリは 3 種類あります。

バイナリ	実行環境	用途
misterclaw	MiSTer（ARM7）	サーバー — MiSTer 本体で実行します
misterclaw-send	どこでも	コマンドを直接実行する CLI クライアント
misterclaw-mcp	お使いのマシン	MCP サーバー — AI エージェントと MiSTer を橋渡しします

ダウンロードと対応プラットフォーム

ソースリポジトリではなく、GitHub Releases から実行ファイルをダウンロードしてください。リリースワークフローでは、以下のターゲット向けにビルドされます。

プラットフォーム	アーキテクチャ	ダウンロード
MiSTer	Linux ARMv7	misterclaw-linux-arm7 デーモン
Linux	x86-64、ARM64、ARMv7	CLI および MCP サーバー
macOS	Intel x86-64、Apple Silicon ARM64	CLI および MCP サーバー
Windows	x86-64	CLI および MCP サーバー（.exe）

Windows 向けのダウンロードは v0.8.0 以降に含まれています。それより前のリリースには含まれていない場合があります。デーモンは MiSTer 上でのみ動作し、Windows や macOS では動作しません。Linux/macOS では、ダウンロードしたクライアントに chmod +x <filename> を実行して実行可能にしてください。

Windows では、ダウンロードした実行ファイルを PowerShell で使用します。例：

.\misterclaw-send-windows-amd64.exe -H mister-fpga status

MCP クライアントの command には、misterclaw-mcp-windows-amd64.exe の絶対パスを指定してください。JSON 内のパスではバックスラッシュをエスケープする必要があります。例：C:\\Tools\\misterclaw-mcp-windows-amd64.exe。

リリースワークフローでは、タグ付きリリースをビルドします（初期ワークフローに感謝します：stt）。新しい CI 生成リリースには、ソースコミット、コンパイラのバージョン、ターゲットの一覧を記録した SHA256SUMS と build-metadata.json が含まれます。ブランチ、PR、手動での CI 実行では、プレビュー用アーティファクトのみが生成されます。公開には、main の履歴に基づくバージョンタグのプッシュと、テストの合格が必要です。メンテナーはタグをプッシュする前に、リリースとライセンスの準備状況を確認する必要があります。main の履歴に含まれていること自体は、レビュー承認の証明にはなりません。CI を追加しても、新しいリリースは作成されません。

MiSTer へのクイックインストール

scp misterclaw root@<mister-ip>:/media/fat/Scripts/
ssh root@<mister-ip> "/media/fat/Scripts/misterclaw --install"

または、手動でインストールすることもできます。バイナリを MiSTer にコピーしてから、misterclaw --install を実行します。これにより /media/fat/Scripts/ にコピーされ、起動時の自動実行が設定されます。同じ操作を繰り返しても問題ありません。

アンインストールするには、次を実行します：/media/fat/Scripts/misterclaw --uninstall

セキュリティ

⚠️ ポート 9900 をインターネットに公開しないでください。 ClawExec プロトコルには認証も暗号化もありません。

• Tailscale VPN（推奨）— 暗号化され、認証機能があり、どこからでも利用できます
• ローカルネットワークのみ — ポート 9900 へのアクセスを LAN 内に限定してください
• ポート 9900 をルーターやファイアウォール経由で転送することは絶対にしないでください

アーキテクチャ

Agent ←MCP→ misterclaw-mcp ←TCP→ MiSTer:9900 (misterclaw server)
Agent ←CLI→ misterclaw-send ←TCP→ MiSTer:9900 (misterclaw server)

MCP サーバーと CLI クライアントは、ClawExec プロトコル（TCP 経由の改行区切り JSON、ポート 9900）を使って MiSTer と通信します。

システムの動的検出

MiSTerClaw は、ROM フォルダー、インストール済みのコア、MGL ファイルをスキャンして、すべてのシステムを自動検出します。設定は不要です。ゲームが十分にそろった MiSTer には、通常 70 以上のシステムがあります。検出結果（ROM ファイルの完全な一覧を含む）はディスクにキャッシュされます。初回起動時にスキャンしてキャッシュを構築し、以降の起動では即座に読み込まれます。ゲームやドライブを追加した後は、rescan コマンドを使用してください。

ソースからのビルド

# MiSTer server (ARM7)
GOOS=linux GOARCH=arm GOARM=7 go build -ldflags="-s -w" -o misterclaw ./cmd/misterclaw/

# CLI client
go build -ldflags="-s -w" -o misterclaw-send ./cmd/misterclaw-send/

# MCP server
go build -ldflags="-s -w" -o misterclaw-mcp ./cmd/misterclaw-mcp/

ライセンス

MIT