Gearsystem MCP — ユースケース, インストール & ライブデモ

なぜ使うのか

主な機能

MCP サーバー内蔵 — 単一バイナリでエミュレーター＋デバッガー＋MCP を提供
stdio および HTTP トランスポート対応（--mcp-stdio または --mcp-http --mcp-http-port N）
MCP 経由のヘッドレス実行により、自動化やエージェント駆動のセッションが可能
CPU ブレークポイント、メモリアクセスブレークポイント、ステップ実行、逆アセンブリ
グラフィックスデバッグ用の VRAM およびパレット検査

ライブデモ

実際の動作

gearsystem.replay ▶ 準備完了

0/0

インストール

クライアントを選択

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config を開く。保存後、アプリを再起動。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Cursor は Claude Desktop と同じ mcpServers スキーマを使用。プロジェクト設定はグローバルより優先。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Cline サイドバーの MCP Servers アイコンをクリックし、"Edit Configuration" を選択。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop と同じ形式。Windsurf を再起動して反映。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "gearsystem",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ]
    }
  ]
}

Continue はマップではなくサーバーオブジェクトの配列を使用。

~/.config/zed/settings.json

{
  "context_servers": {
    "gearsystem": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearsystem"
        ]
      }
    }
  }
}

context_servers に追加。保存時に Zed がホットリロード。

claude mcp add gearsystem -- TODO 'See README: https://github.com/drhelius/Gearsystem'

ワンライナー。claude mcp list で確認、claude mcp remove で削除。

ユースケース

実用的な使い方： Gearsystem

タイトル画面でクラッシュする自作マスターシステム ROM をデバッグする

👤 レトロ自作ゲーム開発者 ⏱ ~30 min advanced

使うタイミング： WLA-DX でビルドした ROM が頭の中では正しく動くはずなのに、Gearsystem のタイトル画面でフリーズする場合。

前提条件

MCP を有効にしてビルドした Gearsystem — drhelius/Gearsystem をクローンし、MCP_README.md の手順に従ってビルド
ROM と対応する .sym シンボルファイル — アセンブラ（WLA-DX、asm6 など）の出力

フロー

ヘッドレスで起動し、クラッシュ箇所にブレークポイントを設定する

Gearsystem MCP で ROM を起動して、ラベル init_vdp に CPU ブレークポイントを設定してから実行して。✓ コピーしました

→ ブレークポイントで実行が停止する
CPU と VRAM の状態を検査する

Z80 レジスタと VRAM の先頭 32 バイトを表示して。初期化のこの時点でおかしいところはある？✓ コピーしました

→ レジスタダンプと、期待値と実際の値に関する所見
ステップ実行しながら特定のメモリ領域を監視する

$C000 にメモリアクセスブレークポイントを追加して、そこに書き込みが発生するまでステップ実行して。✓ コピーしました

→ 問題の命令で停止する

結果： 根本原因（例：VRAM が安全な状態になる前に VDP レジスタに書き込んでいた）と、正確な命令アドレスの特定。

注意点

シンボルが読み込まれていない — アドレスが不透明になる — .sym が正確な ROM ビルドと一致していることを確認し、必要に応じて再ビルドして整合性を取る
タイミング関連のバグが実機でのみ再現し、エミュレーターでは再現しない — エミュレーターには限界がある。バスタイミングのエッジケースについては、実機の SMS でテストすること

組み合わせ： filesystem

所有する ROM をリバースエンジニアリングしてメモリマップを作成する

👤 自身またはパブリックドメインの ROM を記録する保存活動家および開発者 ⏱ ~60 min advanced

使うタイミング： 技術解析記事や逆アセンブリを書いていて、メモリマップが必要な場合。

フロー

ROM を実行し、重要なタイミングで検査する

ROM を起動して VBlank でブレークし、$C000-$DFFF の WRAM をダンプして。次に 1 フレーム実行して再度ダンプして。✓ コピーしました

→ 差分比較用の 2 つの WRAM スナップショット
差分を取って変数と思われるアドレスを特定する

2 つのスナップショットを比較して。どのアドレスが変化した？それらは何だと考えられる？（カウンタ、ポインタ、スプライト座標など）✓ コピーしました

→ 根拠を伴う変数マップの仮説

結果： 手動で精緻化できる初版のメモリマップ。

注意点

所有していない商用著作権付き ROM のリバースエンジニアリングは法的にグレーゾーン — 自身が所有する ROM またはパブリックドメインの ROM にのみ使用すること。商用 ROM の RAM マップを公開する際は、各法域のフェアユース規定を考慮すること

コミットごとに ROM のスモークテストを自動化する

👤 CI パイプラインを持つ自作ゲーム開発者 ⏱ ~25 min intermediate

使うタイミング： 「タイトル画面までクラッシュせずに起動できること」を CI ゲートにしたい場合。

フロー

MCP セッションをスクリプト化する

Gearsystem MCP をヘッドレスで起動し、ROM を 600 フレーム実行して、無効なオペコードで CPU が停止した場合はゼロ以外を返すスクリプトを書いて。✓ コピーしました

→ 明確な終了コードを持つシェルスクリプト
CI に組み込む

それを main への push ごとに実行される GitHub Actions ワークフローにまとめて。✓ コピーしました

→ 動作する CI ステップ

結果： 手動で ROM を読み込む前にリグレッションを検出するスモークテスト。

組み合わせ： github

組み合わせ

他のMCPと組み合わせて10倍の力を

gearsystem + github

デバッグから修正のコミットまでを一連の流れで行う

ROM の issue #12 を再現して、障害のあるアドレスを特定し、src/vdp.asm の 1 行修正で PR を作成して。✓ コピーしました

gearsystem + filesystem

.sym ファイルをデバッガーと併用して、アドレスをラベルに変換する

./build/game.sym を読み込んで、アドレス $03A7 のラベルを教えて。✓ コピーしました

ツール

このMCPが提供する機能

ツール	入力	呼び出すタイミング	コスト
run	(none)	ブレーク後に実行を再開する	free (local)
pause	(none)	検査のために実行を停止する	free
step	n?: int	命令を 1 ステップずつ実行する	free
set_breakpoint	address: hex, kind: cpu\|read\|write	PC のヒットまたはメモリアクセスを監視する	free
read_memory	address: hex, length: int	WRAM／VRAM／カートリッジ領域を検査する	free
disassemble	address: hex, instructions: int	PC 周辺のコードを読む	free
get_registers	(none)	任意の検査タイミングで使用する	free
dump_vram	start?: hex, length?: int	グラフィックスのデバッグ時に使用する	free

コストと制限

運用コスト

APIクォータ: なし — 完全にローカルで動作するプロセス
呼び出しあたりのトークン: メモリダンプは大きくなる場合があります。範囲を絞るとレスポンスを小さく保てます
金額: 無料、GPL-3.0 ライセンス
ヒント: フルページが本当に必要でない限り、小さなメモリウィンドウ（16〜64 バイト）をリクエストしてください。

セキュリティ

権限、シークレット、影響範囲

認証情報の保管： 不要

データ送信先： ローカルで動作します。MCP サーバーは stdio または指定した HTTP ポートにバインドされます

--mcp-http を公開する場合は、127.0.0.1 のみにバインドしてください — エンドポイントには認証がありません。
読み込まれる ROM は任意の信頼できないデータである可能性があります。エミュレーターはサンドボックス化されていますが、プロセスに追加の権限を付与しないでください。

トラブルシューティング

よくあるエラーと対処法

MCP flags not recognized — MCP フラグが認識されない

ビルドが MCP サポートなしでコンパイルされています。MCP_README.md の手順に従い、フラグを有効にして再ビルドしてください。

確認： gearsystem --help | grep mcp

Breakpoint never hits — ブレークポイントに到達しない

シンボル解決がずれている可能性があります。ラベルの代わりに生のアドレスを試してください。ROM が実際に読み込まれていることも確認してください。

確認： Use get_registers to confirm PC is moving

HTTP transport refused connection — HTTP トランスポートの接続が拒否される

ポートが使用中でないか確認し、エミュレーターが --mcp-http --mcp-http-port 7777 で起動されていることを確認してください。

確認： curl http://127.0.0.1:7777/

代替案

Gearsystem 他との比較

代替案	代わりに使う場面	トレードオフ
Emulicious	Game Boy／SMS などのフル GUI デバッガーが必要な場合	MCP 非対応。手動操作のみ
BizHawk	マルチシステムの TAS／デバッグ用途	MCP ではなく Lua スクリプトで操作

その他

リソース

📖 GitHub の公式 README を読む

🐙 オープンな issue を見る

🔍 400以上のMCPサーバーとSkillsを見る