Godot MCP

godot-mcp

AI アシスタントに Godot エディターで目と手を与え、実際にプレイテストできる実行中のゲームを操作できるようにします。

この MCP サーバーの特徴

Godot MCP サーバーはいくつかあり、そのほとんどはシーンを開いてノードを操作できます。このサーバーは、より難しい課題、つまりエージェントが自分の作業を検証できるようにすることを中心に構築されています。ゲームを実行し、プレイヤーのように操作し、実際に何が起きたかを観察して、変更が主張どおりの効果をもたらしたことを確かめます。スクリーンショットやエラーログをあなたが何度もやり取りして渡す必要はありません。

それを可能にする、ほかでは見られない機能は次のとおりです。

• 決定論的なプレイテスト。 ゲームの時計を停止し、正確なゲーム時間の分だけ進めます（または、条件が満たされるまで進めます）。その間に入力を与えることもできます。観察中にゲームが先に進むことはありません。
• 低コストな観察。 エンティティの状態（位置、速度、アニメーション状態、独自のカスタムデータなど）を、構造化された JSON としてリアルタイムに取得できます。「画面上で何が起きているか」という質問のほとんどは、スクリーンショットにビジョントークンを使わずに回答できます。
• 実際の入力。 アナログ強度付きの名前付きアクション、ゲームパッドのボタンやスティックのベクトル、修飾キーの組み合わせを含む生のキー入力、相対的なマウス視点操作、テキスト入力に対応しています。入力シーケンスは正確なタイミングで実行でき、ゲームの状態を変化させたことも検証できます。
• シナリオのセットアップ。 実行中のゲーム内で GDScript を実行できます。武器を付与する、ウェーブ 3 までスキップする、テスト用ボットをスポーンさせる、といった操作を、ゲームコードにデバッグ用フックを組み込まずに行えます。

エージェントがボス戦をテストする場合の動作例を紹介します。

godot_editor_edit   run frozen=true           # boot with game time frozen at frame 0
godot_exec          GameState.wave = 3        # set up the scenario worth testing
godot_game_time     step_until "tree.get_nodes_in_group('boss').size() >= 1"
godot_runtime_state digest                    # exact positions and state — no pixels, no guessing
godot_game_time     step 500ms + dodge input  # play the moment that matters
godot_editor_read   screenshot_game           # and a screenshot when it's actually worth the tokens

コピー＆ペーストを減らして、創作に集中しましょう。

クイックスタート

1. AI アシスタントを設定する

godot-mcp を MCP クライアントに追加します。設定例については、インストールガイド（Claude Desktop、Claude Code、VSCode/Copilot など）をご覧ください。簡単な手順は次のとおりです。

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@satelliteoflove/godot-mcp"]
    }
  }
}

2. Godot アドオンをインストールする

npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project

Godot で有効にします：プロジェクト > プロジェクト設定 > プラグイン > Godot MCP

3. 開発を始める

Godot プロジェクトを開き、AI アシスタントを再起動して、開発を始めましょう。接続できない場合は、トラブルシューティングガイドをご覧ください。

含まれる内容

21 個のツール、86 個のアクションを収録しています。API のドキュメント全文はツールリファレンスをご覧ください。

ツール	機能
godot_scene	シーンを開いて保存します（.tscn を直接記述してから開くことで、新しいシーンを作成できます）
godot_node_read / godot_node_edit	有効なプロパティ、インスタンス化されたサブシーンを含むシーンツリー全体を調べ、ノードを検索します。プロパティの更新や親の変更もできます
godot_editor_read / godot_editor_edit	エディターの状態、選択項目、スクリーンショット、エディターのエラーログを確認します。実行／停止／再起動や 2D ビューポートの制御もできます
godot_project	プロジェクト情報、設定、アドオンのバージョンの不一致、古い設定の検出を行います
godot_animation_read / godot_animation_edit	キーフレームまでアニメーションを照会します。トラックとキーフレームを作成し、エディターですぐにプレビューできます
godot_tilemap_read / godot_tilemap_edit	TileMapLayer のセルを読み取り、編集します（.tscn 内では base64 エンコードされており、ブリッジを使う方法が唯一の手段です）
godot_gridmap_read / godot_gridmap_edit	GridMap のセルを読み取り、編集します。同様の仕組みです
godot_resource	型に応じた形式でリソースを調べます。SpriteFrames、TileSet、マテリアル、テクスチャに対応しています
godot_scene3d	空間的な推論に役立つ、エンジンが計算した 3D トランスフォーム、境界ボックス、可視性を取得します
godot_docs	エディターのバージョンに一致する Godot ドキュメントを、整形された Markdown として取得します
godot_input	実行中のゲームに入力を送ります。アクション、ゲームパッド、キー入力、マウス視点操作、テキストに対応しています
godot_profiler	メトリクスのスナップショットとフレームごとの時系列データを取得し、スパイクを検出します
godot_runtime_state	実行中のゲームの状態を JSON で取得します。単発のダイジェスト、監視ウィンドウ、シグナルのタイムラインに対応しています
godot_game_time	ゲームクロックの停止、ステップ実行、条件を満たすまでのステップ実行を行い、決定論的に状態を観察します
godot_exec	実行中のゲーム内で GDScript を実行し、テストシナリオをセットアップします
godot_validate_meshes	ライティングの不具合に見せかける、破損したプロシージャルメッシュデータを検出します

ツールの構成について：ツールは読み取りと書き込みの境界で分かれているため、すべての godot_*_read ツール（およびその他の読み取り専用ツール）は、クライアントの権限設定で安全に自動許可でき、書き込みは制限されたままです。関連する操作は引き続き 1 つのツール内のアクションとしてまとめられているため、エージェントのコンテキストが使わない定義であふれることはありません。シーンやノードの作成、スクリプトのアタッチ、シグナルの接続など、プロジェクトファイルを直接編集すればエージェントが実行できる操作は、意図的にツールとして重複して提供していません。このブリッジが対応するのは、ファイルでは扱えないエディターの状態、検証、バイナリ形式でエンコードされたセルデータ、実行中のゲームです。--read-only フラグを使えば、変更せずに確認する用途にも対応できます。

依頼の例

エージェントにできることを、自然なプロンプトでいくつか紹介します。

• 「ゲームを実行してタイトル画面のスクリーンショットを撮ってください。1280x720 でもレイアウトは崩れませんか？」
• 「プレイヤーが東側の壁をすり抜けます。再現してからコリジョン形状を調べ、原因を教えてください。」
• 「第 2 ウェーブが出現するまでゲームをステップ実行し、敵全員の位置と速度を教えてください。」
• 「左スティックを半分倒した状態で 2 秒間維持してください。歩行アニメーションは正しくブレンドされますか？」
• 「ゲームプレイを 10 秒間プロファイルして、フレームのスパイクの原因を探してください。」
• 「Player にヒット時のフラッシュアニメーションを追加してください。0.2 秒かけて赤く変化させ、元に戻します。」

実行時の状態をより詳しく観察するには、主要なノードを mcp_watch グループに追加するか、ノードに _mcp_state() メソッドを定義してください。実行時状態ガイドをご覧ください。

仕組み

┌─────────────────┐   stdio    ┌─────────────────┐  WebSocket   ┌──────────────────┐  debugger   ┌──────────────┐
│   MCP client    │ ◄────────► │  godot-mcp      │ ◄──────────► │  Bridge addon    │ ◄─────────► │ Running game │
│ (Claude, etc.)  │            │  server (Node)  │   :6550      │  (Godot editor)  │    wire     │  (autoload)  │
└─────────────────┘            └─────────────────┘              └──────────────────┘             └──────────────┘

サーバーはローカル WebSocket 経由でエディターアドオンと通信し、アドオンは Godot 独自のデバッガープロトコルを通じて実行中のゲームにアクセスするため、ゲームプロセスに追加のポートや設定は必要ありません。アドオンはデフォルトで 127.0.0.1 にバインドします。WSL2 は完全にサポートされています（自動検出、ホスト IP の検出、設定可能なバインドモード）。詳しくはインストールガイドをご覧ください。

接続のライフサイクル、単一クライアントのポリシー、または内部での時間停止ステップ実行の仕組みが気になりますか？アーキテクチャガイドで詳しく説明しています。

minimal-godot-mcp との併用に最適

@ryanmazzolini による minimal-godot-mcp は、このサーバーがカバーしない機能を正確に補います。高速な静的 GDScript チェックのための LSP 診断と、DAP 経由での実行中ゲームのコンソール出力です。このサーバーはエディターブリッジが必要なすべてをカバーします。重複も競合もありません。両方を実行すれば、エージェントは静的解析とゲームコンソールに加えて、エディターとランタイムを完全に制御できます。

注意点が 1 つあります。Godot エディターが一度に提供できる godot-mcp クライアントは 1 つだけです（たとえば、MCP 設定を継承したサブエージェントなどの）追加クライアントは、セッションを横取りせずに順番を待ちます。詳しくはトラブルシューティングをご覧ください。

ドキュメント

• インストールガイド — Claude Desktop、Claude Code、VSCode/Copilot などの MCP クライアント設定
• v4 への移行 — 名前が変更されたツール、削除されたアクション、許可リストの更新
• トラブルシューティング — 接続チェックリスト、CLI スモークテスト、一般的な修正方法
• Claude Code セットアップガイド — Godot プロジェクト用 CLAUDE.md テンプレート
• ランタイム状態ガイド — mcp_watch と _mcp_state() を介してゲームの状態をエージェントに公開
• ツールリファレンス — 全 21 ツールの詳細な API ドキュメント
• アーキテクチャガイド — サーバー、アドオン、ゲームブリッジの連携方法
• コントリビューション — 開発環境のセットアップ、ツールの追加、リリースプロセス
• 変更履歴 — リリース履歴

要件

• Godot 4.5+（アドオンは 4.5 で導入された Logger クラスを使用します）
• Node.js 20+
• stdio に対応した任意の MCP クライアント

開発

cd server
npm install && npm run build
npm test                # unit + schema-snapshot tests
npm run test:protocol   # wire-level smoke of the built server
npm run generate-docs

エージェント評価ハーネス（npm run eval）もあります。実際のプロジェクトに対して、ヘッドレス Claude Code で現実的なタスクを実行します。詳しくはserver/evals/README.mdをご覧ください。Godot は起動しません。エディターを開いておいてください。

コントリビューションを歓迎します。このプロジェクトでは、現実の時間を浪費する問題を解決するツールを重視しています。大規模なものを作る前にCONTRIBUTING.mdをお読みいただくか、issue を開いて、適切な形を一緒に検討しましょう。

ライセンス

MIT