Godot Peek MCP

🚀 Godot Peek MCP

Godotエディタのランタイムを調査するためのMCPサーバーです。シーンを実行し、出力をキャプチャし、デバッガーの状態を検査できます。

🚀 クイックスタート

なぜ別のGodot MCPが必要なのか？

他のGodot MCPは、LLMがすでに行えるエディターアクションをラップしています。Claudeは.tscn、.tres、.gdファイルを直接編集できるため、シーンファイルを編集できるのに「ノードを追加する」ツールは必要ありません。

このMCPは、ランタイムの可視性に焦点を当てています。出力パネル、デバッガーの状態、スクリーンショットなど、通常はエディターとの対話が必要な内容です。

セットアップ

ダウンロード、コピー、接続。3つの手順です。

1. ダウンロード

Releasesからお使いのOS用のリリースをダウンロードします。

適当な場所（例：~/tools/godot-peek-mcp/）に展開します。以下のファイルが得られます。

• godot-peek-mcp — MCPサーバーのバイナリ
• addons/godot_mcp/ — Godotプラグイン

2. Godotプラグインのインストール

addons/godot_mcpフォルダをGodotプロジェクトにコピーし、your-project/addons/godot_mcp/に配置します。その後、Godotで有効にします。Project > Project Settings > Plugins > Godot Peek MCP > Enable

出力パネルに以下のようなメッセージが表示されるはずです（ソケット名はプロジェクトディレクトリから派生します）。

GodotPeekPlugin: listening on /tmp/godot-peek-my-game.sock

3. MCPサーバーの登録

使用するMCPクライアントを選択します。

claude mcp add godot-peek ~/tools/godot-peek-mcp/godot-peek-mcp

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

{
  "mcpServers": {
    "godot-peek": {
      "command": "/home/YOUR_USER/tools/godot-peek-mcp/godot-peek-mcp"
    }
  }
}

以上でセットアップは完了です。

macOS: クォランタインの解除

macOSはインターネットからダウンロードした未署名のバイナリをブロックする場合があります。セキュリティ警告が表示された場合は、以下のコマンドを実行します。

xattr -cr ~/tools/godot-peek-mcp/godot-peek-mcp
xattr -cr ~/your-project/addons/godot_mcp/bin/

✨ 主な機能

• シーン制御：メイン/現在/特定のシーンを実行し、ゲームを停止する
• 変数オーバーライド：起動時にオートロード変数を設定する（例：デバッグモードを有効にする）
• 出力キャプチャ：出力パネルを読み取る
• デバッガー統合：エラー、スタックトレース、ローカル変数、パフォーマンスモニター
• デバッガー制御：ブレークポイントを設定し、コードをステップ実行し、一時停止/再開する
• ランタイム検査：実行中のゲームのノードツリーとプロパティを確認する
• スクリーンショット：エディタービューポートまたは実行中のゲームをキャプチャする
• 式評価：実行中のゲームで任意のGDScriptを評価する

💻 使用例

基本的な使用法

シーン制御

overrides：起動時にオートロード変数を設定します。形式：{"AutoloadName": {"property": value}} 例：{"DebugManager": {"debug_mode": true}}

出力とデバッグ

スクリーンショット

デバッガー制御

注意：ブレークポイントはGodotの組み込みスクリプトエディターでのみ機能します。外部エディターを使用している場合、ブレークポイントはトリガーされません。

式評価

これを使用して、ゲームの状態をクエリし、変数を設定し、またはメソッドを呼び出すことができます。

高度な使用法

LLMユーザー向けのヒント

• 反復的なデバッグ：シーンを実行 → 出力を確認 → コードを修正 → 繰り返す。run_*ツールは起動時のクラッシュを自動検出し、スタックトレースを返します。
• オーバーライドでテスト：{"DebugManager": {"debug_mode": true}}で実行して、コードを編集せずにデバッグ機能を有効にします。
• ランタイムで検査：get_remote_scene_treeを使用してインスタンス化されているものを確認し、get_remote_node_propertiesを使用して値を確認します。
• テスト用の自動停止：timeout_secondsを使用して短時間実行し、get_outputを確認します。自動テストループに適しています。
• 視覚的なバグのためのスクリーンショット：get_screenshot target=gameでプレイヤーが見るものを正確に表示します。
• 式を評価：print文を使用せずに任意のゲーム状態をクエリします。evaluate_expression "get_tree().current_scene.name"または状態を変更します。evaluate_expression "get_node('/root/Main/Player').set('health', 100)"（.set()を使用します — 代入演算子はExpressionクラスでは機能しません）。注意：式がランタイムエラーを引き起こす場合、ゲームが応答する前にクラッシュするため、ツール呼び出しはタイムアウトします。

📚 ドキュメント

ゲームのエクスポート

MCPプラグインはエディター専用です。ゲームをエクスポートするには、拡張ファイルを除外する必要があります。そうしないと、ビルドされたゲームは起動時にエラーになります。

Export > Resources > Filters to excludeに以下を追加します。 addons/godot_mcp/bin/*, addons/godot_mcp/godot_peek.gdextension, addons/godot_mcp/plugin.*

ランタイムヘルパースクリプト（peek_runtime_helper.gd）はオートロードとして登録されているため含まれたままですが、エクスポートビルドでは自動的に初期化をスキップします。

注意事項

• 出力：出力パネルから読み取ります。print()、push_error()、push_warning()、およびエディターメッセージ。
• デバッガーツール：それぞれのデバッガータブから取得します。frame_indexはローカル変数のスタックフレームを選択します（0=トップ）。重要：get_debugger_stack_traceとget_debugger_localsは、ゲームがランタイムエラーまたはブレークポイントで一時停止しているときにのみデータを持ちます。通常の実行中に呼び出すと空の結果が返されます。
• リモート検査（get_remote_scene_tree、get_remote_node_properties）は、ゲームが実行中のときのみ機能します。
• モニター（get_monitors）は、エンジンのパフォーマンスデータを表示します。FPS、メモリ使用量、描画コール、物理ステータスなど。
• スクリーンショットは/tmp/godot_peek_*.pngに保存されます。エディターのスクリーンショットはアクティブな2D/3Dビューポートをキャプチャします。ゲームのスクリーンショットには、プラグインが自動的に追加するオートロードが必要です。

🔧 技術詳細

┌─────────────────────┐     stdio      ┌─────────────────────┐
│   Claude Code #1    │◄──────────────►│  Go MCP Server #1   │──┐
└─────────────────────┘                └─────────────────────┘  │
┌─────────────────────┐     stdio      ┌─────────────────────┐  │ Unix socket
│   Claude Code #2    │◄──────────────►│  Go MCP Server #2   │──┤ /tmp/godot-peek-<project>.sock
└─────────────────────┘                └─────────────────────┘  │
                                            ...                 │
                                       ┌────────────────────────▼┐
                                       │  C++ GDExtension        │
                                       │  (addons/godot_mcp)     │
                                       └────────────┬────────────┘
                                                    │ UDP (game features)
                                                    │ port 6971
                                       ┌────────────▼────────────┐
                                       │  Runtime Helper         │
                                       │  (running game)         │
                                       └─────────────────────────┘

複数のMCPクライアントセッションを同時に接続できます。各セッションは独自のGo MCPサーバープロセスを生成し、C++拡張機能はすべての接続を同時に受け入れます。

📦 インストール

必要条件

• Godot 4.4、4.5、または4.6
• Linux x86_64またはmacOS arm64（Apple Silicon）

ソースからビルド

リリースを使用する代わりにソースからビルドする場合は、以下のコマンドを実行します。

# go mcp server
go build -ldflags="-s -w" -o godot-peek-mcp ./cmd/godot-peek-mcp

# c++ extension (requires godot-cpp — set GODOT_CPP_PATH or defaults to ~/Code/godot-cpp)
cd extension && scons platform=linux target=editor