GodotLens

GodotLens：GDScript プロジェクトを Godot 自身の視点で把握

AI エージェントがプロジェクトについて Godot 自身に質問できる MCP サーバーです。シンボルがどこで使われているか、メソッドの実際のシグネチャ、編集内容がコンパイルできるか、シーンがどのように接続されているかを確認できます。 また、ゲームを実行してその様子を確認し、操作できます。エージェントは人がプレイしなくても、ゲームが意図どおりに動作するか検証できます。

その理由

テキストだけを頼りに GDScript を編集するエージェントは、推測するしかありません。コードの呼び出しとコメントを区別できず、あなたの Godot バージョンの CharacterBody2D にどのメソッドが存在するかも分からず、.tscn 内でシグナルハンドラーが名前によって接続されていることも、実行時に何が起きたかも確認できません。

GodotLens は、こうした疑問に自ら答えることはありません。エンジンに問い合わせ、その回答を返します。Godot 4.7.1 で、take_damage が player.gd で定義され、enemy.gd から 2 回、player.gd から 1 回呼び出され、コメントにも記述されているプロジェクトで測定した結果です。

方法	結果
grep take_damage	コメントを含む 5 件の一致
gdscript_references	実際の呼び出し箇所がちょうど 4 件。コメントは含まれません

「すべての判断を Godot に委ねる」という原則が、回答の信頼性を支えています。また、ツール名から回答の出どころが分かります。gdscript_* は言語サーバーです。scene_* と project_* はプロジェクト上でエンジンを実行します。debug_* はエディターのデバッガーです。runtime_* は GodotLens が起動し、接続しているゲームです。

要件

	必要なもの
プロジェクトを開いた Godot 4.6 以降のエディター	gdscript_* と debug_* — 言語サーバーとデバッグアダプターはエディター内で動作します
GODOT_BIN、./godot/ ディレクトリ、または PATH から利用できる Godot バイナリ	scene_*、project_*、runtime_* — これらはエンジンを独自に実行するため、エディターは不要です
Python 3.10 以降、または npx 用の Node.js 16 以降	このサーバーの実行

言語サーバーが 4.5 で大きく変更され（URI エンコーディング）、4.6 でも変更された（ドキュメントの所有権）ため、Godot 4.6 が最低バージョンです。それより古いバージョンは、誤って解釈したまま動作するのではなく、明確なメッセージを表示して拒否します。

インストール

npx（推奨）。パッケージにはサーバーが含まれており、実行時の依存関係はありません。

{
  "mcpServers": {
    "godotlens": {
      "command": "npx",
      "args": ["-y", "godotlens-mcp"]
    }
  }
}

pip

pip install godotlens-mcp

{
  "mcpServers": {
    "godotlens": { "command": "godotlens-mcp" }
  }
}

実行方法

セットアップ	動作するもの	操作
エディターが開いている — 通常の開発	すべて	エディター設定（下記）で フォーカスがないときにリソースをインポート をオンにします。
エディターなし — CI、スクリプト	scene_*、project_*、runtime_*	gdscript_* と debug_* を使うには、ヘッドレスエディターを起動します：godot --path <project> --editor --headless --lsp-port 6005 --dap-port 6006
GodotLens が起動するゲーム（runtime_run）	上記いずれかに加えて runtime_*	不要です。各ゲームは GodotLens に接続する独立したプロセスであり、エディターの実行スロットは使いません。

フォーカスがないときにリソースをインポート。 エディターは、ウィンドウにフォーカスが当たったときにのみ、新規ファイルや変更されたファイルを検知します。エージェントが操作するエディターにフォーカスが当たることはないため、新しい class_name スクリプトは認識されず、それを使うすべてのスクリプトで名前が未宣言として報告され、ゲームの解析に失敗します。また、新しいアセットもインポートされないままになります。この設定をオンにすると、エディターは 0.5 秒ごとに再スキャンします。Godot 4.7 では interface/editor/behavior/import_resources_when_unfocused、Godot 4.6 では interface/editor/import_resources_when_unfocused です。1 つのプロジェクトだけに設定するには、Godot 4.6 の設定名を project.godot の [editor_overrides] の下に追加します（Godot 4.7 では読み込み時に移行されます）。同期されたファイルが、エディターに登録されていないクラスを参照している場合、gdscript_sync_file は短時間待機してから、そのクラス名とこの説明の場所を示します。

GodotLens が起動するゲーム。 runtime_run は、--remote-debug で GodotLens を指定してゲームを起動するため、ゲームはエディターのデバッガーに接続するのと同じ方法で GodotLens に接続します。ゲームはデフォルトでヘッドレスで実行されます。ウィンドウも音声もなく、フォーカスを奪うこともありません。runtime_screenshot の場合に限り windowed: true を指定できます。この場合、ウィンドウは遠く離れた位置で開き、音声はミュートされ、その後画面外に完全に移動されます。そのため、一瞬だけ隅が少し見えることがあります。スクリプトエラーは報告されますが、ゲームの実行は停止しません。この方法で起動したゲームは、停止されたとき、GodotLens が終了したとき、また Windows では GodotLens が強制終了された場合にも終了します。GodotLens が起動するすべてのエンジン実行と同様に、ゲームのログはそれぞれ専用の一時ファイルに保存されます。Godot はプロジェクトごとに最新 5 件のログのみを保持するため、自分で実行したプレイやテストのログもその中に残ります。

ヘルパー。 runtime_eval と runtime_input にはゲーム内のコードが必要です。GodotLens は、その実行時に限り --script を使って自身の helper.gd をゲームに渡します。プロジェクトには何も書き込まれません。Godot はプロジェクトの設定、入力マップ、自動読み込みを引き続き読み込み、ヘルパーがシーンを開きます。独自のメインループタイプを設定しているプロジェクトはヘルパーなしで実行され、helper: false を指定した runtime_run はゲームをそのまま実行します。

複数のエージェント。 1 つの Claude Code セッション内のサブエージェントは、1 つの GodotLens プロセスを共有します（gdscript_status と runtime_status がその server_pid を報告します）。呼び出しは並行して実行されるため、時間のかかる runtime_run やシーンのチェックが、ほかのエージェントのクエリを妨げることはありません。また、各エージェントは独自のゲームを runtime_run で実行できます（GODOT_RUNTIME_MAX_SESSIONS のデフォルトは 4 です）。ただし、調整されないことが 2 つあります。debug_run はエディターの単一の実行スロットを使うため、2 回目の実行を開始すると最初の実行は停止します。また、2 つのエージェントが同じファイルに書き込むと互いの変更を上書きするため、一度に書き込むエージェントは 1 つにしてください。

ループ

ツールはひとつのサイクルを中心に設計されています。一度目を通せば、このドキュメントの残りはリファレンスとして使えます。

flowchart LR
    U["<b>Understand</b><br/>gdscript_find<br/>gdscript_references<br/>gdscript_hover"]
    W["<b>Write</b><br/>gdscript_engine_api<br/>gdscript_complete<br/>gdscript_validate"]
    S["<b>Sync</b><br/>gdscript_sync_file"]
    V["<b>Verify</b><br/>gdscript_diagnostics<br/>scene_validate<br/>project_validate"]
    R["<b>Run</b><br/>runtime_run"]
    O["<b>Observe &amp; act</b><br/>runtime_tree · runtime_inspect<br/>runtime_output · runtime_eval<br/>runtime_input · runtime_screenshot"]

    U --> W --> S --> V --> R --> O
    O -- "fix, then runtime_reload" --> W
    O -- "something is wrong" --> U

    classDef step fill:#f5f7fa,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    class U,W,S,V,R,O step;

1. 理解する。 gdscript_find で名前からシンボルを検索し、gdscript_references と gdscript_hover でその使われ方と型を確認します。
2. 記述する。 gdscript_engine_api で記憶に頼らず実際のシグネチャを確認し、gdscript_complete でシーンを考慮した候補を取得し、gdscript_validate で内容をディスクに書き込む 前に チェックします。
3. 同期する。 Godot の言語サーバーはファイルシステムを監視しません。.gd ファイルを編集した後に gdscript_sync_file を呼び出さないと、古いテキストをもとに応答し続けます。
4. 検証する。 コンパイルエラーには gdscript_diagnostics、コンパイラーでは検出できないシーンの問題には scene_validate、ファイルの移動後には project_validate を使います。
5. 実行する。 runtime_run でゲームを起動し、最初の出力とエラーを取得します。
6. 観察して操作する。 実行中のツリーと値を確認し、入力を送信し、式を評価してスクリーンショットを撮ります。コードを修正し、runtime_reload で実行中のゲームに反映します。

全体を通して、次の2つの決まりが適用されます。

• すべての行および文字のパラメーターは0始まりです。 LSP と同じ形式です。エディターの1行目は0行目です。gdscript_find を使えば、手動で位置を計算する必要はほとんどありません。
• 重要な結果には verified フラグが付与されます。 診断リストが空でも verified: false の場合、Godot から応答がなかったことを意味します。問題がないと確認されたわけではありません。

ツール

コードの理解

ツール	説明
gdscript_find	名前 から 宣言を検索します。以下のツールにそのまま渡せる位置を返します。
gdscript_definition	シンボルの定義場所を返します。
gdscript_references	プロジェクト全体にあるすべての参照を返します。Godot 4.6 以降では、すべての .gd ファイルを再解析するため、処理に時間がかかります。
gdscript_references_in_file	1つのファイル内にある出現箇所を返します。こちらのほうがはるかに高速です。Godot 4.7 以降。
gdscript_hover	シンボルの型情報とドキュメントを返します。
gdscript_symbols	ファイルのシンボルツリーを返します。
gdscript_signature_help	呼び出し箇所のパラメーター情報を返します。
gdscript_symbols_batch、gdscript_definitions_batch、gdscript_references_batch	複数のファイルまたは位置を対象に、同じ処理を1回の呼び出しで行います。

コードの記述

ツール	説明
gdscript_engine_api	使用中の正確なビルドから、エンジンクラスまたはメンバーのシグネチャとドキュメントを取得します。親クラスから継承されたメンバーも含まれます。Godot の API を記憶に頼る代わりに使用してください。
gdscript_complete	指定位置の補完候補を返します。唯一の シーンを考慮した クエリであり、実際の $NodePath エントリーと、所有ノードに実際に存在するシグナルを含みます。
gdscript_validate	内容をディスクに書き込まずに、提案された内容にエラーがないか確認します。
gdscript_rename	シンボルの名前を変更します。Godot で名前を変更できない場合は処理を拒否し、更新できないシーンファイルにも同じ名前がある場合は警告します。

Godot との同期を保つ

ツール	説明
gdscript_sync_file	変更したファイルを1つ同期して、診断結果を返します。エディターにまだ登録されていない新しい class_name がある場合は、登録されるまで短時間待機します。
gdscript_sync_files	複数のファイルを一度に同期します。
gdscript_release_file	ファイルを解放し、言語サーバーが再びディスクから読み取るようにします。
gdscript_diagnostics	1つ以上のファイルのエラーと警告を返します。
gdscript_status	接続状態を確認します。動作がおかしい場合は、まずここから確認してください。

プロジェクトとシーン

これらは Godot のバイナリを実行するため、継承シーンやインスタンス化されたシーンも含め、エンジンが構築するとおりにシーンを解決します。.tscn をテキストとして解析しないため、エディターは不要です。

ツール	説明
project_config	ProjectSettings を通じて、オートロードのシングルトン、入力アクション名、class_name のグローバル、メインシーンを取得し、各ファイルが存在するかどうかも示します。
project_validate	ファイルの移動後に解決できなくなった参照を調べます。シーンとリソースの依存関係、オートロードスクリプト、メインシーンが対象です。UID で解決できる参照は壊れていません。
scene_state	ノードツリー、型、スクリプトのアタッチ、unique_name_in_owner フラグ、エクスポートされた値、シグナル接続を取得します。
scene_validate	シーン内で Godot が気付かないまま誤って処理する内容を調べます。エラー：接続先のない接続、存在しないシグナル、引数の数が一致しないハンドラー、不明なノード型、ノードに適合しないスクリプト、存在しない親、重複した名前。警告：不明なプロパティ、値の型の誤り、シーン内にないノードへの NodePath。

エディター内のデバッガー

Godot はエディターから Debug Adapter Protocol サーバーを提供します。アドオンは不要です。これらはエディター独自の実行スロットを使うため、同時に実行できるゲームは1つだけです。ブレークポイントを設定するには、この方法を使います。

ツール	説明
debug_run	エディターからプロジェクトを実行し、出力と構造化されたすべてのエラーを返します。args: ["--headless"] を指定すると、ウィンドウなしで実行します。
debug_output	ゲームの出力（print、stdout、stderr）と、ファイル、行、スタックを含む構造化エラー（push_error、push_warning、エンジンおよびスクリプトのエラー）を取得します。呼び出すたびに出力を読み取ります。
debug_set_breakpoints	ファイルにブレークポイントを設定します。
debug_stack_trace	実行が一時停止している場所のコールスタックを取得します。一時停止していない場合は空です。
debug_inspect	スタックフレーム内の変数をスコープ別に取得します。
debug_evaluate	ブレークポイントで式を評価します。Godot が回答を返さずにゲームを再開する場合は拒否されます。
debug_continue、debug_pause、debug_step_over	実行を制御します。
debug_terminate	実行中のゲームを停止します。
debug_status	アダプターの接続状態と、ゲームが実行中か一時停止中かを取得します。

GodotLens が起動するゲーム

runtime_run はゲームを独立したプロセスとして起動し、GodotLens に直接接続します。そのため、複数のエージェントがそれぞれ同時にゲームを1つずつ実行でき、エディターも不要です。

ツール	説明
runtime_run	ゲームを起動します。デフォルトではヘッドレスで実行します。セッション ID と、最初の出力およびエラーを返します。
runtime_output	ゲームの出力と、発生した構造化エラーすべてを、ファイル、行、スタックとともに取得します。
runtime_tree	実行時に作成されたノードも含め、実行中のシーンツリーを取得します。
runtime_inspect	ノードの現在のプロパティ値を取得します。スクリプト変数も含まれます。
runtime_set	プロパティを変更して値を読み戻します。値はプロパティの型に変換されます。
runtime_eval	ゲームの実行中に、シーン、オートロード、エンジンのシングルトン、class_name のグローバルを対象として式を評価します。
runtime_input	プレイヤーと同じように入力アクションを押します。is_action_just_pressed で検出できます。
runtime_reload	状態を維持したまま、変更されたスクリプトをホットリロードします。コンパイルできないスクリプトがある場合は拒否されます。
runtime_screenshot	ウィンドウ表示で実行中のゲームが描画している内容を、画像として取得します。
runtime_monitors	FPS、フレーム時間、ノード数と孤立ノード数、メモリ、カスタムモニターを履歴付きで取得します。
runtime_pause、runtime_time_scale、runtime_step	ゲームを停止、スローダウン、またはステップ実行します。
runtime_status、runtime_stop	GodotLens が実行中のゲームを一覧表示して停止します。

制限事項

結果を信頼する前に知っておくべきことです。

言語サーバーから見えないもの

• .gd ファイルのみを読み取ります。 .tscn の [connection] ブロックで接続されたシグナルハンドラーは認識されないため、そのハンドラーの名前を変更すると、シーンは存在しないメソッドを参照したままになります。このため scene_validate があり、gdscript_rename は警告を表示します。
• Autoload 名と入力アクション名は単なる文字列です。 GameState.add_score(1) と Input.is_action_pressed("jump") は一切検証されません。記述する前に project_config で確認してください。
• 新しいファイルが認識されるのは、エディターのファイルシステムスキャンを経由した場合のみです（実行方法を参照）。スキャンがフォルダーを検出するのは、その更新日時が変わったときだけです。Godot は更新日時を秒単位で保持するため、スキャンと同じ秒に作成されたファイルは見落とされることがあります。新しいクラスがその1秒後も認識されない場合、GodotLens はそのフォルダー内に空の隠しファイル（.godotlens-rescan）を作成して削除します（エディターはドットで始まる名前を無視するためです）。これにより、次のスキャンでファイルが再読み込みされます。プロジェクトにこれ以外のものが書き込まれることはありません。
• gdscript_references は 4.6 以降では負荷が高く、プロジェクト内のすべてのスクリプトを再解析します。1ファイルだけで十分な場合は gdscript_references_in_file を使ってください。

ゲームの実行

• ヘッドレスゲームではピクセルを取得できません。 runtime_screenshot には windowed: true が必要です。runtime_step にも同じ設定が必要です。Godot は次の描画されたフレームの後にのみ、再び一時停止するためです。
• ホットリロードの対象はスクリプトのみです。 編集した .tscn ファイルや、新規または変更されたアセットを反映するには再起動が必要です。コンパイルに失敗したスクリプトは実行中のゲームで無効になるため、runtime_reload はエラーのあるスクリプトを拒否します。エラーの確認にはエディターの言語サーバーが必要です。エディターがない場合は、未確認のまま再読み込みし、その旨を伝えます。
• runtime_eval は完全な GDScript ではなく、Godot の Expression です。呼び出し、演算子、メンバーアクセスには対応しますが、文や代入には対応しません。呼び出しは実際に実行されます。
• ブレークポイントはエディター内にしかありません（debug_*）。debug_evaluate が機能するのは、スクリプトインスタンスのあるフレームで一時停止している場合のみです。静的関数内や解析エラーで停止した場合は拒否されます。実行すると Godot がゲームを再開してしまい、応答できないためです。
• Godot はゲームから報告される内容にレート制限を設けています（プロジェクト設定の network/limits/debugger/*）。大量に出力するゲームでは、エンジンによって出力が切り詰められます。
• Linux と macOS では、GodotLens が正常終了するとゲームも停止しますが、GodotLens を強制終了するとゲームは実行し続けます。Windows では、どちらの場合もゲームは停止します（ジョブオブジェクトによる制御）。

シーンとプロジェクトのチェック

• scene_* と project_config はゲームと同様に Autoload を起動するため、Autoload を使うスクリプトもコンパイルされます。project_validate と runtime_monitors は何も起動しません。
• 一部のシーンの誤りは、どのエンジン API からも確認できません。 [sub_resource] 内の不明なプロパティは、読み込み時に Godot によって破棄されるため、何かが確認する前に失われます。
• project_validate はシーンとリソースを検証します。 スクリプト内の壊れた preload() または extends のパスはコンパイルエラーとなり、gdscript_diagnostics が報告します。

1つのプロジェクトにつきエディターは1つです。 同じプロジェクトを2つ目のエディターで開くと（たとえば、GUI エディターと並行してヘッドレスエディターを起動すると）、そのエディター独自の認識に基づいて .godot/ のクラスキャッシュが書き換えられ、もう一方が登録したクラスが削除されることがあります。開いているエディターに GodotLens を接続してください。

アーキテクチャ

4つのチャネルが1つのプロセスにあります。各ツールグループはそのうち1つにのみ対応しており、これによって応答元を把握できます。

flowchart TD
    Agent["AI Agent<br/>(and its subagents)"]
    GL["<b>GodotLens</b><br/>MCP server · JSON-RPC 2.0<br/>Python 3.10+ · no dependencies"]

    Agent <-- "stdio" --> GL

    GL -- "TCP 6005<br/>language server" --> Editor
    GL -- "TCP 6006<br/>debug adapter" --> Editor
    GL -- "subprocess<br/>--headless --script" --> Binary
    Game -- "TCP, game connects back<br/>remote debugger protocol" --> GL

    Editor["<b>Godot Editor</b><br/>your open editor<br/><i>gdscript_* · debug_*</i>"]
    Binary["<b>Godot binary</b><br/>run on demand<br/><i>scene_* · project_*</i>"]
    Game["<b>Games GodotLens launched</b><br/>one process each<br/><i>runtime_*</i>"]

    classDef svc fill:#eef4fb,stroke:#4a6785,stroke-width:1px,color:#1b2733;
    classDef godot fill:#f3f0fb,stroke:#6b5b95,stroke-width:1px,color:#1b2733;
    class Agent,GL svc;
    class Editor,Binary,Game godot;

MCP、LSP、DAP のプロトコルと Godot のバイナリ値形式は標準ライブラリを直接使って実装されているため、このパッケージには実行時依存関係が一切なく、npm バンドルは少数の .py ファイルと .gd ファイルで構成されています。

設定

変数	デフォルト	説明
GODOT_LSP_HOST	127.0.0.1	言語サーバーのホスト
GODOT_LSP_PORT	6005	言語サーバーのポート。公式の VS Code 拡張機能では 6008 を使用します
GODOT_DAP_HOST	127.0.0.1	デバッグアダプターのホスト
GODOT_DAP_PORT	6006	debug_* で使用するデバッグアダプターのポート
GODOT_BIN	auto	Godot の実行ファイル。scene_*、project_*、runtime_* で必要です
GODOT_PROJECT_ROOT	auto	プロジェクトのルート。project.godot を探して親ディレクトリをたどり、自動検出します
GODOT_LSP_TIMEOUT	15	言語サーバーからの応答を1回受信するまで待機する秒数
GODOT_DIAGNOSTICS_TIMEOUT	8	同期後、診断結果を待機する秒数
GODOT_VERSION	auto	機能検出を上書きします
GODOT_FIND_FILE_LIMIT	60	プロジェクト全体の検索時に gdscript_find が調べるファイルの最大数
GODOT_RUNTIME_MAX_SESSIONS	4	runtime_run が同時に実行し続けるゲームの最大数

貢献

pip install -e ".[dev]"
pytest -m "not integration"   # no Godot needed
ruff check .

統合テストでは実際のヘッドレス Godot を起動し、利用できない場合は問題なくスキップします。ゲームウィンドウを開くテストは、明示的に実行するよう指定した場合、または Linux で仮想ディスプレイを使用している場合にのみ実行されます。

GODOT_BIN=/path/to/godot pytest -m integration
GODOTLENS_WINDOWED_TESTS=1 GODOT_BIN=/path/to/godot pytest -m windowed

CI では Linux、Windows、macOS で Python 3.10～3.13 を使用してテストスイートを実行し、3つすべての OS で実際の Godot を使って統合テストを実行します。また、ビルドした npm tarball をインストールして実行します。

ライセンス

Apache License 2.0 — LICENSE と NOTICE を参照してください。