Godot MCP

Godot MCP - フルコントロール

AI アシスタントに Godot ゲームエンジンの完全な制御を提供する、包括的なModel Context Protocol（MCP）サーバーです。ネットワーク、3D／2D レンダリング、UI コントロール、オーディオエフェクト、アニメーションツリー、ファイル I/O、ランタイムコード実行、プロパティの検査、シーン操作、シグナル管理、物理演算、プロジェクト作成など、多岐にわたる157 個のツールを備えています。

謝辞

このプロジェクトは、Solomon Elias（Coding-Solo）によるgodot-mcpを基盤として構築・拡張したものです。オリジナルのプロジェクトでは、TypeScript MCP サーバー、ヘッドレス GDScript 操作システム、TCP ベースのランタイムインタラクションサーバーなど、基盤となるアーキテクチャが提供されていました。素晴らしいオープンソースの成果によって実現してくださり、ありがとうございます！

新機能（オリジナルからの改善点）

オリジナルの godot-mcp には、基本的なプロジェクト管理とシーン作成用のツールが20個ありました。このフォークでは、次の主な機能を追加し、157 個のツールに拡張しました。

3.1 の新機能

• validate_script のオートロード解決 - スクリプトの検証では、--check-only を _init() で実行する代わりに、_initialize() で（プロジェクトのオートロードが登録された後に）SceneTree を通じて対象をコンパイルするようになりました。これにより、オートロードシングルトンへの参照で誤った Identifier not found エラーが発生しなくなり、実際の構文／型エラーは引き続き検出されます。複数のオートロードを参照するスクリプトを含むゲーム全体のビルドで検証済みです。
• manage_input_map のイベント結合 - 既存の入力アクションに2つ目のキーを追加すると、重複した actionname= 行を書き込むのではなく、そのアクションの events 配列に結合されるようになりました（physical_keycode の重複排除を含む）。以前はこれによって project.godot の形式が不正になり、先に設定したバインドが通知なく破棄されていました。

3.0 の新機能

• .NET／C# のサポート - C# プロジェクトのひな形を作成し、C# スクリプトを生成できます（dotnet: true を指定した create_project、create_csharp_script）。.csproj の SDK バージョンは、インストール済みの Godot に合わせられます。
• GDScript の診断 - ゲームを実行せずに、スクリプトの構文エラーと型エラーを検証できます（validate_script、および git で変更されたファイルまたはプロジェクト全体のファイルを対象とする validate_scripts）。
• ヘッドレスシーン操作とランタイムインタラクションサーバー全体の正確性と堅牢性を改善（リソース型のプロパティが保持されるようになり、親の変更が機能し、ランタイムコマンドがリクエスト ID で対応付けられ、警告をエラーとして扱うプロジェクトでもツールが動作するようになりました）。Godot 4.4 以降が必要です。最新の Godot 4.7 でテスト済みで、正常に動作します。

ランタイムコードの実行

• game_eval - 実行中のゲーム内で任意の GDScript コードを実行し、戻り値を取得します
• 非同期 GDScript コードの完全な await サポート
• ゲームが一時停止中でも動作します（PROCESS_MODE_ALWAYS）

ランタイムノードの検査と操作

• game_get_property ／ game_set_property - パスを指定して、任意のノードのプロパティを読み取り／書き込みます
• game_call_method - 引数を指定して、任意のノードのメソッドを呼び出します
• game_get_node_info - プロパティ、シグナル、メソッド、子ノードを含む、ノードの完全なイントロスペクション
• game_instantiate_scene - 実行中のゲームにシーンを動的に追加します
• game_remove_node - 実行時にノードを削除します
• game_change_scene - 実行時にシーンを切り替えます
• game_reparent_node - ノードを別の親に移動します

シグナルシステム

• game_connect_signal - 実行時にシグナル接続を設定します
• game_disconnect_signal - シグナル接続を解除します
• game_emit_signal - 引数を指定してシグナルを発行します

アニメーションとトゥイーン

• game_play_animation - AnimationPlayer を制御します（再生、停止、一時停止、一覧表示）
• game_tween_property - イージングを設定可能な、滑らかなプロパティアニメーション

ゲームの制御とデバッグ

• game_pause - ゲームを一時停止／再開します
• game_performance - FPS、フレーム時間、メモリ、オブジェクト数、描画呼び出し
• game_wait - N フレーム待機します（タイミングが重要な操作向け）
• game_get_nodes_in_group - グループでノードを検索します
• game_find_nodes_by_class - 特定のクラスのノードをすべて検索します

ヘッドレスシーン操作（実行中のゲームは不要）

• read_scene - 任意の .tscn ファイルを解析し、プロパティを含むノードツリー全体を JSON として取得します
• modify_scene_node - シーンファイル内のノードプロパティを変更します
• remove_scene_node - シーンファイルからノードを削除します
• attach_script - シーン内のノードに GDScript ファイルをアタッチします
• create_resource - .tres リソースファイルを作成します（マテリアル、テーマなど）

プロジェクト管理

• read_project_settings - project.godot を構造化された JSON として解析します
• modify_project_settings - プロジェクト設定をプログラムで変更します
• list_project_files - 拡張子でプロジェクトファイルを一覧表示し、絞り込みます

ファイル入出力

• read_file / write_file / delete_file - Godot プロジェクト内のファイルシステムに完全にアクセスします
• create_directory - スクリプト、シーン、アセット用のディレクトリ構造を作成します

エラーとログの取得

• game_get_errors - 前回の呼び出し以降に発生した新しい push_error/push_warning メッセージを取得します
• game_get_logs - 前回の呼び出し以降に実行中のゲームから出力された新しい print 出力を取得します

拡張入力

• game_key_hold / game_key_release - 移動テスト（WASD など）のためにキーを押したままにします
• game_scroll - マウスのスクロールホイールイベント
• game_mouse_drag - 複数フレームにわたり、2 点間をドラッグします
• game_gamepad - ゲームパッドのボタンおよび軸入力イベント

プロジェクトの作成と設定

• create_project - 新しい Godot プロジェクトをゼロから作成します（.NET/C# プロジェクトのひな形を生成するには dotnet: true を渡します）
• create_csharp_script - Godot .NET プロジェクトに C# スクリプトを作成します
• manage_autoloads - オートロードを追加、削除、または一覧表示します
• manage_input_map - 入力アクションとキー割り当てを追加、削除、または一覧表示します
• manage_export_presets - エクスポートプリセットの設定を作成または変更します

.NET / C# サポート

• create_project と dotnet: true - Godot .NET プロジェクトのひな形を生成します（使用中の Godot のバージョンに対応する Godot.NET.Sdk を使った .csproj と、"C#" 機能フラグ）
• create_csharp_script - 慣用的な C# スクリプトを生成します（partial クラス、正しい _Ready／_Process オーバーライドシグネチャ）。Godot がアタッチできるよう、クラス名はファイル名と常に一致します
• get_project_info - isDotnet フィールドを返します

GDScript の診断

• validate_script - 1 つの GDScript ファイルをヘッドレスで検査し、構文エラーと型エラーを確認して、{ valid, errors: [{ message, file, line }] } を返します
• validate_scripts - Git で変更されたすべての .gd ファイル（またはプロジェクト全体）を一括検証し、エージェントがゲームの実行前に編集内容を確認できるようにします

カメラ、物理、オーディオ

• game_get_camera / game_set_camera - 2D／3D カメラの状態を取得・制御します
• game_raycast - 物理レイを投射します（2D と 3D を自動判別します）
• game_get_audio - オーディオバスのレイアウトと再生中のストリームを取得します
• game_spawn_node - プロパティを指定して、実行時に任意のノードタイプを作成します
• game_set_shader_param - マテリアルのシェーダーパラメーターを設定します
• game_audio_play / game_audio_bus - オーディオの再生とバスを総合的に制御します
• game_navigate_path - ナビゲーションパスを照会します（2D／3D）
• game_tilemap - TileMapLayer のセルを取得・設定します
• game_add_collision - 物理ボディにコリジョンシェイプを追加します
• game_environment - ポストプロセス（フォグ、グロー、SSAO、トーンマッピングなど）を設定します
• game_manage_group - ノードをグループに追加・削除します
• game_create_timer - タイマーノードをプログラムで作成します
• game_set_particles - GPUParticles2D/3D のプロパティとプロセスマテリアルを設定します
• game_create_animation - 値、メソッド、ベジェ、オーディオのトラックとキーフレームを含むアニメーションを作成します
• export_project - ヘッドレスでのプロジェクトのエクスポートビルドを実行します（CI/CD 対応）
• game_serialize_state - ノードツリー全体の状態を JSON として保存・読み込みます
• game_physics_body - 質量、速度、減衰、摩擦、反発を設定します
• game_create_joint - 物理ジョイント（ピン、スプリング、ヒンジ、コーン、スライダー）を作成します
• game_bone_pose - キャラクターアニメーション用にスケルトンのボーンポーズを取得・設定します
• game_ui_theme - 色、定数、フォントサイズのテーマオーバーライドを適用します
• game_viewport - SubViewport ノードを作成・設定します
• game_debug_draw - デバッグ用ジオメトリ（線、球、ボックス）を描画します

ネットワーキング

• game_http_request - ヘッダーと本文を指定して HTTP GET/POST/PUT/DELETE を実行します
• game_websocket - WebSocket クライアントの接続・切断とメッセージの送信を行います
• game_multiplayer - ENet マルチプレイヤーのサーバー／クライアントを作成、切断します
• game_rpc - ノード上の RPC メソッドを呼び出すか設定します

システムとウィンドウの制御

• game_script - 実行時にノードのスクリプトをアタッチ、デタッチするか、ソースを取得します
• game_window - ウィンドウのサイズ、フルスクリーン、タイトル、位置を取得・設定します
• game_os_info - プラットフォーム、ロケール、画面、アダプター、メモリ情報を取得します
• game_time_scale - Engine.time_scale とタイミング情報を取得・設定します
• game_process_mode - ノードのプロセスモード（ポーズ可能／常時／無効）を設定します
• game_world_settings - 重力、物理 FPS、ワールド設定を取得・設定します

高度なシグナルと入力

• game_list_signals - ノード上のすべてのシグナルと接続を一覧表示します
• game_await_signal - タイムアウトを指定してシグナルを待機し、引数を返します
• game_touch - タッチの押下／解放／ドラッグとジェスチャーをシミュレートします
• game_input_state - 押されているキー、マウス位置、接続済みのゲームパッドを照会します
• game_input_action - 実行時の InputMap アクションと強度を管理します

3D レンダリングとジオメトリ

• game_csg - ブーリアン演算を使用して CSG ノードを作成・設定します
• game_multimesh - インスタンシング用の MultiMeshInstance3D を作成・設定します
• game_procedural_mesh - 頂点データから ArrayMesh を使ってメッシュを生成します
• game_light_3d - 3D ライト（ディレクショナル／オムニ／スポット）を作成・設定します
• game_mesh_instance - プリミティブメッシュを使って MeshInstance3D を作成します
• game_gridmap - GridMap のセルを設定・取得・クリアし、使用中のセルを照会します
• game_3d_effects - ReflectionProbe、Decal、または FogVolume を作成します
• game_gi - VoxelGI または LightmapGI を作成・設定します
• game_path_3d - Path3D/Curve3D を作成し、カーブポイントを管理します
• game_sky - プロシージャルスカイ／物理スカイを使用して Sky を作成・設定します
• game_camera_attributes - カメラの被写界深度、露出、自動露出を設定します
• game_navigation_3d - NavigationRegion3D を作成・設定し、ベイクします
• game_physics_3d - Area3D の照会と、点／シェイプの交差テストを行います

2D システム

• game_canvas - CanvasLayer と CanvasModulate を作成／設定します
• game_canvas_draw - 2D 描画：線／四角形／円／ポリゴン／テキスト／クリア
• game_light_2d - 2D ライトとライトオクルーダーを作成／設定します
• game_parallax - ParallaxBackground とレイヤーを作成／設定します
• game_shape_2d - Line2D／Polygon2D のポイントを操作します
• game_path_2d - Path2D／Curve2D の管理と AnimatedSprite2D
• game_physics_2d - Area2D のクエリと、2D の点／シェイプの交差判定

高度なアニメーション

• game_animation_tree - AnimationTree のステートマシンの遷移とパラメーター
• game_animation_control - AnimationPlayer のシーク／キュー／速度／情報を制御します
• game_skeleton_ik - SkeletonIK3D の開始／停止／ターゲット位置の設定

高度なオーディオ

• game_audio_effect - オーディオバスエフェクトの追加／削除／設定
• game_audio_bus_layout - オーディオバスとルーティングの作成／削除／並べ替え
• game_audio_spatial - AudioStreamPlayer3D の空間プロパティを設定します

エディターとプロジェクトのツール

• rename_file - プロジェクト内のファイル名を変更または移動します
• manage_resource - .tres／.res リソースファイルを読み取りまたは変更します
• create_script - テンプレートから GDScript ファイルを作成します
• validate_script - ヘッドレスで GDScript ファイルの構文／型エラーをチェックします（実行は不要です）
• validate_scripts - GDScript ファイルを一括チェックします。デフォルトでは git で変更されたファイルが対象ですが、すべてのファイルも指定できます
• manage_scene_signals - .tscn ファイル内のシグナル接続を一覧表示／追加／削除します
• manage_layers - プロジェクト内の名前付きレイヤー定義を一覧表示／設定します
• manage_plugins - エディタープラグインを一覧表示／有効化／無効化します
• manage_shader - .gdshader ファイルを作成または読み取ります
• manage_theme_resource - Theme の .tres リソースを作成／読み取り／変更します
• set_main_scene - project.godot のメインシーンを設定します
• manage_scene_structure - .tscn シーン内のノード名を変更／複製／移動します
• manage_translations - プロジェクト内の翻訳ファイルを一覧表示／追加／削除します
• game_locale - 実行時にロケールを設定／取得し、文字列を翻訳します

UI コントロール

• game_ui_control - Control のフォーカス、アンカー、ツールチップ、マウスフィルターを設定します
• game_ui_text - LineEdit／TextEdit／RichTextLabel のテキスト操作
• game_ui_popup - Popup／Dialog／Window ノードを表示／非表示／ポップアップします
• game_ui_tree - Tree コントロール：項目の取得／選択／折りたたみ／追加／削除
• game_ui_item_list - ItemList／OptionButton：項目の取得／選択／追加／削除
• game_ui_tabs - TabContainer／TabBar：現在のタブの取得／設定
• game_ui_menu - PopupMenu／MenuBar：メニュー項目の追加／削除／取得
• game_ui_range - ProgressBar／Slider／SpinBox／ColorPicker の値の取得／設定

レンダリングとリソース

• game_render_settings - MSAA、FXAA、TAA、スケーリングモード／スケールを取得／設定します
• game_resource - 実行時のリソースの読み込み、保存、またはプリロード

堅牢性の向上

• 再入可能性ガード - 非同期操作中の並行したコマンド処理を防ぎます
• 完全な型変換 - Vector2／3、Color、Quaternion、Basis、Transform2D／3D、AABB、Rect2、およびすべての PackedArray 型をサポートします
• スマートなプロパティ型検出 - ノードの get_property_list() を使用して型を自動変換します
• PackedArray のシリアライズ - 文字列へのフォールバックではなく、適切な JSON 配列を使用します
• 柔軟なエラー処理 - 依存関係が見つからない場合、シーンの読み取りを生の .tscn テキストにフォールバックします

全 157 ツール

プロジェクト管理（7 ツール）

ツール	説明
launch_editor	プロジェクトの Godot エディターを起動します
run_project	Godot プロジェクトを実行し、出力を取得します
stop_project	実行中のプロジェクトを停止します
get_debug_output	コンソール出力とエラーを取得します
get_godot_version	インストール済みの Godot バージョンを取得します
list_projects	ディレクトリ内の Godot プロジェクトを検索します
get_project_info	プロジェクトのメタデータを取得します

シーン管理 (7 個のツール)

ツール	説明
create_scene	ルートノードタイプを指定して新しいシーンを作成します
add_node	既存のシーンにノードを追加します
load_sprite	テクスチャを Sprite2D ノードに読み込みます
export_mesh_library	シーンを MeshLibrary としてエクスポートします
save_scene	シーンを保存します (オプションのバリアントパス付き)
get_uid	ファイルの UID を取得します (Godot 4.4+)
update_project_uids	リソースを再保存して UID を更新します

ヘッドレスシーン操作 (5 個のツール)

ツール	説明
read_scene	シーンツリー全体を JSON として読み取ります
modify_scene_node	シーンファイル内のノードプロパティを変更します
remove_scene_node	シーンファイルからノードを削除します
attach_script	GDScript をシーンノードにアタッチします
create_resource	.tres リソースファイルを作成します

プロジェクト設定 (3 個のツール)

ツール	説明
read_project_settings	project.godot を JSON として解析します
modify_project_settings	プロジェクト設定を変更します
list_project_files	プロジェクトファイルを一覧表示/フィルタリングします

ランタイム入力 (4 個のツール)

ツール	説明
game_screenshot	スクリーンショットをキャプチャします (base64 PNG)
game_click	指定した位置をクリックします
game_key_press	キー押下または入力アクションを送信します
game_mouse_move	マウスを移動します

ランタイム検査 (3 個のツール)

ツール	説明
game_get_ui	表示されているすべての UI 要素を取得します
game_get_scene_tree	シーンツリー構造全体を取得します
game_get_node_info	ノードの詳細なイントロスペクションを行います

ランタイムコード実行 (1 個のツール)

ツール	説明
game_eval	戻り値付きで任意の GDScript を実行します

ランタイムノード操作 (7 個のツール)

ツール	説明
game_get_property	任意のノードプロパティを取得します
game_set_property	任意のノードプロパティを設定します (自動型変換)
game_call_method	ノード上の任意のメソッドを呼び出します
game_instantiate_scene	PackedScene を実行中のツリーに追加します
game_remove_node	ツリーからノードを削除します
game_change_scene	別のシーンに切り替えます
game_reparent_node	ノードを新しい親に移動します

ランタイムシグナル (5 個のツール)

ツール	説明
game_connect_signal	シグナルをメソッドに接続します
game_disconnect_signal	シグナルを切断します
game_emit_signal	引数付きでシグナルを発行します
game_list_signals	ノード上のすべてのシグナルと接続を一覧表示します
game_await_signal	タイムアウト付きでシグナルを待機し、引数を返します

ランタイムアニメーション (2 個のツール)

ツール	説明
game_play_animation	AnimationPlayer を制御します
game_tween_property	イージング付きでプロパティをトゥイーンします

ランタイムユーティリティ (5 個のツール)

ツール	説明
game_pause	ゲームを一時停止/再開します
game_performance	FPS、メモリ、ドローコールを取得します
game_wait	N フレーム待機します
game_get_nodes_in_group	グループでノードを照会します
game_find_nodes_by_class	クラスタイプでノードを検索します

ファイル I/O (4 個のツール)

ツール	説明
read_file	Godot プロジェクトからテキストファイルを読み取ります
write_file	テキストファイルを作成または上書きします
delete_file	プロジェクトからファイルを削除します
create_directory	プロジェクト内にディレクトリを作成します

エラーとログのキャプチャ (2 個のツール)

ツール	説明
game_get_errors	前回の呼び出し以降の新しいエラー/警告を取得します
game_get_logs	前回の呼び出し以降の新しい print 出力を取得します

入力の拡張（8 ツール）

ツール	説明
game_key_hold	キーを押したままにします（自動的には離しません）
game_key_release	押したままのキーを離します
game_scroll	マウスのスクロールホイールイベント
game_mouse_drag	N フレームかけて 2 点間をドラッグします
game_gamepad	ゲームパッドのボタンまたは軸の入力
game_touch	タッチの押下／解放／ドラッグとジェスチャーをシミュレートします
game_input_state	押されているキー、マウスの位置、接続中のパッドを照会します
game_input_action	実行時の InputMap アクションと強度を管理します

プロジェクトの作成（5 ツール）

ツール	説明
create_project	新しい Godot プロジェクトを作成します（C# 用に dotnet: true をサポート）
create_csharp_script	Godot .NET プロジェクトに C# スクリプトを作成します
manage_autoloads	オートロードを追加、削除、または一覧表示します
manage_input_map	入力アクションを追加、削除、または一覧表示します
manage_export_presets	エクスポートプリセットを作成または変更します

高度な実行時機能（24 ツール）

ツール	説明
game_get_camera	アクティブなカメラの位置、回転、ズームを取得します
game_set_camera	アクティブなカメラを移動または回転させます
game_raycast	レイを飛ばし、衝突結果を返します
game_get_audio	オーディオバスのレイアウトと再生中のストリームを取得します
game_spawn_node	実行時に任意の種類の新しいノードを作成します
game_set_shader_param	ノードのマテリアルのシェーダーパラメーターを設定します
game_audio_play	AudioStreamPlayer ノードを再生、停止、または一時停止します
game_audio_bus	オーディオバスの音量、ミュート、またはソロを設定します
game_navigate_path	2 点間のナビゲーション経路を照会します
game_tilemap	TileMapLayer ノードのセルを取得または設定します
game_add_collision	物理ボディノードに衝突形状を追加します
game_environment	環境とポストプロセスの設定を取得または設定します
game_manage_group	ノードをグループに追加または削除するか、グループを一覧表示します
game_create_timer	設定済みの Timer ノードを作成します
game_set_particles	GPUParticles2D/3D ノードのプロパティを設定します
game_create_animation	トラックとキーフレームを含むアニメーションを作成します
game_serialize_state	ノードツリーの状態を JSON として保存または読み込みます
game_physics_body	物理ボディのプロパティ（質量、速度）を設定します
game_create_joint	2 つのボディ間に物理ジョイントを作成します
game_bone_pose	Skeleton3D ノードのボーンポーズを取得または設定します
game_ui_theme	Control ノードにテーマのオーバーライドを適用します
game_viewport	SubViewport ノードを作成または設定します
game_debug_draw	3D 空間にデバッグ用の線、球、またはボックスを描画します

ビルドとエクスポート（1 ツール）

ツール	説明
export_project	プリセットを使用して Godot プロジェクトをエクスポートします

ネットワーキング（4 ツール）

ツール	説明
game_http_request	ヘッダーと本文を指定して HTTP GET/POST/PUT/DELETE を実行します
game_websocket	WebSocket クライアントの接続、切断、メッセージ送信を行います
game_multiplayer	ENet マルチプレイヤーのサーバー／クライアント作成と切断を行います
game_rpc	ノードの RPC メソッドを呼び出すか、設定します

システムとウィンドウ（6 ツール）

ツール	説明
game_script	ノードのスクリプトをアタッチ、デタッチするか、ソースを取得します
game_window	ウィンドウのサイズ、全画面表示、タイトル、位置を取得または設定します
game_os_info	プラットフォーム、ロケール、画面、アダプター、メモリの情報を取得します
game_time_scale	Engine.time_scale と時間情報を取得または設定します
game_process_mode	ノードのプロセスモード（ポーズ可能／常時／無効）を設定します
game_world_settings	重力、物理 FPS、ワールド設定を取得または設定します

3D レンダリングとジオメトリ（13 ツール）

ツール	説明
game_csg	ブーリアン演算で CSG ノードを作成・設定
game_multimesh	インスタンシング用に MultiMeshInstance3D を作成・設定
game_procedural_mesh	頂点データから ArrayMesh を使ってメッシュを生成
game_light_3d	3D ライト（指向性／全方向／スポット）を作成・設定
game_mesh_instance	プリミティブメッシュを使って MeshInstance3D を作成
game_gridmap	GridMap のセルの設定／取得／クリアと、使用中のセルの照会
game_3d_effects	ReflectionProbe、Decal、FogVolume を作成
game_gi	VoxelGI または LightmapGI を作成・設定
game_path_3d	Path3D／Curve3D を作成し、カーブのポイントを管理
game_sky	プロシージャルスカイ／物理ベースのスカイを使って Sky を作成・設定
game_camera_attributes	カメラの被写界深度、露出、自動露出を設定
game_navigation_3d	NavigationRegion3D を作成・設定してベイク
game_physics_3d	Area3D のクエリと、点／形状の交差テスト

2D システム（7 ツール）

ツール	説明
game_canvas	CanvasLayer と CanvasModulate を作成・設定
game_canvas_draw	2D 描画：線／長方形／円／ポリゴン／テキスト／クリア
game_light_2d	2D ライトとライトオクルーダーを作成・設定
game_parallax	ParallaxBackground とレイヤーを作成・設定
game_shape_2d	Line2D／Polygon2D のポイント操作
game_path_2d	Path2D／Curve2D の管理と AnimatedSprite2D
game_physics_2d	Area2D のクエリと、2D の点／形状の交差判定

高度なアニメーション（3 ツール）

ツール	説明
game_animation_tree	AnimationTree のステートマシンの遷移とパラメーター
game_animation_control	AnimationPlayer のシーク／キュー／速度／情報を制御
game_skeleton_ik	SkeletonIK3D の開始／停止とターゲット位置の設定

高度なオーディオ（3 ツール）

ツール	説明
game_audio_effect	オーディオバスエフェクトの追加／削除／設定
game_audio_bus_layout	オーディオバスとルーティングの作成／削除／並べ替え
game_audio_spatial	AudioStreamPlayer3D の空間プロパティを設定

エディターとプロジェクトのツール（14 ツール）

ツール	説明
rename_file	プロジェクト内のファイル名を変更または移動
manage_resource	.tres／.res リソースファイルを読み込みまたは変更
create_script	テンプレートから GDScript ファイルを作成
validate_script	GDScript ファイルの構文／型エラーをチェック（ヘッドレス）
validate_scripts	GDScript ファイルを一括チェック（デフォルトでは Git で変更されたファイル、またはすべて）
manage_scene_signals	.tscn ファイル内のシグナル接続を一覧表示／追加／削除
manage_layers	プロジェクト内の名前付きレイヤー定義を一覧表示／設定
manage_plugins	エディタープラグインを一覧表示／有効化／無効化
manage_shader	.gdshader ファイルを作成または読み込み
manage_theme_resource	Theme .tres リソースを作成／読み込み／変更
set_main_scene	project.godot のメインシーンを設定
manage_scene_structure	.tscn シーン内のノード名を変更／複製／移動
manage_translations	プロジェクト内の翻訳ファイルを一覧表示／追加／削除
game_locale	ロケールの設定／取得と、実行時の文字列翻訳

UI コントロール（8 ツール）

ツール	説明
game_ui_control	Control のフォーカス、アンカー、ツールチップ、マウスフィルターを設定
game_ui_text	LineEdit／TextEdit／RichTextLabel のテキスト操作
game_ui_popup	Popup／Dialog／Window ノードの表示／非表示／ポップアップ
game_ui_tree	Tree コントロール：項目の取得／選択／折りたたみ／追加／削除
game_ui_item_list	ItemList／OptionButton：項目の取得／選択／追加／削除
game_ui_tabs	TabContainer／TabBar：現在のタブを取得／設定
game_ui_menu	PopupMenu／MenuBar：メニュー項目の追加／削除／取得
game_ui_range	ProgressBar／Slider／SpinBox／ColorPicker の値を取得／設定

レンダリングとリソース（2 ツール）

ツール	説明
game_render_settings	MSAA、FXAA、TAA、スケーリングモード／スケールを取得または設定します
game_resource	実行時のリソースを読み込み、保存、またはプリロードします

要件

• Godot Engine 4.4 以降（ヘッドレス操作スクリプトと UID 機能には 4.4 以降が必要です）。最新の Godot 4.7 でテスト済みで、正常に動作します。
• （任意）.NET SDK 8.0 以降と Godot .NET（C#）ビルド。create_project の dotnet: true フラグまたは create_csharp_script を使用する場合にのみ必要です。
• Node.js >= 18.0.0
• MCP に対応した AI アシスタント（Claude Code、Cline、Cursor など）

インストール

git clone https://github.com/tugcantopaloglu/godot-mcp.git
cd godot-mcp
npm install
npm run build

設定

Claude Code

Claude Code の MCP 設定に追加します。

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}

Cline（VS Code）

Cline の MCP 設定（cline_mcp_settings.json）に追加します。

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "disabled": false
    }
  }
}

Cursor

プロジェクトに .cursor/mcp.json を作成します。

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"]
    }
  }
}

実行時ツールの設定

game_* 実行時ツールを使用するには、Godot プロジェクトに MCP インタラクションサーバーのオートロードが必要です。build/scripts/mcp_interaction_server.gd をプロジェクトにコピーし、オートロードとして登録します。

1. build/scripts/mcp_interaction_server.gd をプロジェクトのスクリプトフォルダーにコピーします。
2. Godot で Project > Project Settings > Autoload を開きます。
3. スクリプトを McpInteractionServer という名前で追加します。

サーバーは 127.0.0.1:9090 で待ち受け、ゲームの実行中に TCP 経由で JSON コマンドを受け付けます。

環境変数

変数	説明
GODOT_PATH	Godot 実行可能ファイルへのパス（自動検出を上書きします）
DEBUG	サーバー側の詳細なログを出力するには "true" に設定します
GODOT_MCP_ALLOWED_DIRS	任意です。すべてのプロジェクトツール、プロジェクト検出、エクスポート先を指定したルートに制限します。Windows では ; または ,、その他のシステムでは : または , を使用します。アクセス確認の前に、既存のシンボリックリンクは解決されます。未設定の場合、どのプロジェクトルートも許可されます。

ファイルパスとシーンパスは、シンボリックリンク配下のパスも含め、プロジェクトディレクトリ内にとどめる必要があります。これらの確認は MCP ツールの引数に適用されます。実行時の評価と生成されたスクリプトは Godot プロセスのアカウント権限で実行されるため、信頼できないコードを実行する場合は、別のアカウントまたはコンテナーを使用してください。

実行時ログの保持

game_get_logs と game_get_errors は、任意の cursor および limit 引数を受け付けます。既定のページサイズは 200 行で、最大 500 行です。応答には nextCursor、hasMore、dropped が含まれます。同じ位置から続行するには、nextCursor を渡します。カーソルを指定しない呼び出しは、前回の呼び出しから続行します。各ストリームは最新の 2,000 行を保持し、1 行あたりの最大文字数は 4,096 です。カーソルが保持されている出力より前を指している場合、dropped は true になります。get_debug_output は、保持されているストリームと開始オフセットを返します。

コントリビューターによる検証

開発と CI には Node.js 22.12 以降が必要です。サーバーの実行時要件は package.json に指定されたバージョンのままです。

npm ci
npm test
npm audit --audit-level=moderate

CI は Node.js 22 および 24 で実行され、パッケージの公開やサービスのデプロイは行いません。npm test は最初にサーバーをビルドするため、実行可能ファイルのエントリーテストでは最新のコードが使用されます。テストには、SDK のインメモリトランスポートを使用した実際の MCP リクエスト、ファイルシステム境界の確認、シンボリックリンクによる境界外へのアクセス、プロジェクトのひな形作成、スキーマ検証、カーソルによるページネーションが含まれます。実際の Godot プロジェクトの実行は、エンジンのインストールが必要な統合チェックです。一時プロジェクトを使ったヘッドレススモークテストを有効にするには、コンソール実行可能ファイルのフルパスを GODOT_SMOKE_PATH に設定します。このテストではプロジェクトを作成し、シーンを作成および編集して MCP 経由で読み取り、2 つ目のシーンを保存します。テスト後、一時ファイルは削除されます。

アーキテクチャ

サーバーは、2 つの通信チャネルを使用します。

1. ヘッドレス CLI - ゲームの実行を必要としない操作（シーンの読み取り、変更、リソースの作成）に使用します。Godot を --headless --script godot_operations.gd <operation> <json_params> で実行します。

2. TCP ソケット - 実行中のゲームとのランタイムインタラクションに使用します。mcp_interaction_server.gd オートロードがポート 9090 をリッスンし、TypeScript MCP サーバーから送信された JSON コマンドを処理します。

ソースの構成

パス	説明
src/index.ts	MCP サーバー、ツール定義、すべてのハンドラー
src/utils.ts	副作用のないユーティリティ関数（パラメーターのマッピング、検証、エラーヘルパー）
src/scripts/godot_operations.gd	ヘッドレス GDScript オペレーションランナー
src/scripts/mcp_interaction_server.gd	TCP インタラクションサーバーのオートロード
tests/	Vitest テストスイート

テスト

このプロジェクトでは Vitest を使用しており、5 ファイルにわたって 446 件のテストがあります。

ファイル	テスト数	対象
tests/utils.test.ts	31	パラメーターのマッピング、正規化、パスの検証、エラーレスポンス、バージョン検出
tests/tool-definitions.test.ts	163	定義済みの 155 個すべてのツール、スキーマの妥当性、一意な名前、80 文字未満の説明
tests/handlers.test.ts	225	ゲームコマンド引数の変換、必須パラメーターの検証、ヘッドレス操作のパス確認、ソース構造
tests/dotnet.test.ts	20	.NET 機能フラグ、.csproj の生成、C# スクリプトテンプレートの生成、識別子の検証
tests/validate-script.test.ts	12	GDScript 診断の解析、Git で変更されたファイルの収集

npm test          # run once
npm run test:watch  # watch mode

プロンプトの例

"Run my Godot project and check for errors"

"Eval this in my running game: return get_tree().current_scene.name"

"Get the player's position in the running game"

"Set the player's health to 100"

"Read the test_level.tscn scene and show me the node tree"

"Change the player's speed property in the player.tscn scene file"

"List all .gd files in my project"

"Connect the enemy's 'died' signal to the game manager's 'on_enemy_died' method"

"Tween the camera's position to (0, 10, -5) over 2 seconds with ease-out"

"Get performance metrics - what's my FPS and draw call count?"

"Pause the game and take a screenshot"

"Find all CharacterBody3D nodes in the scene"

"Create a new Godot project called 'MyGame' and write a player script"

"Create a new C# (.NET) Godot project and add a CharacterBody2D script"

"Validate player.gd for errors"

"Check all my changed GDScript files for syntax errors before I run the game"

"Hold down the W key for 2 seconds to test walking"

"Cast a ray from the player downward to check for ground"

"Get the camera position and move it to look at the player"

"Show me the latest error messages from the running game"

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

クレジット

• オリジナルプロジェクト：Solomon Elias (Coding-Solo) による godot-mcp - 基盤となる MCP サーバーアーキテクチャ、ヘッドレス操作システム、TCP インタラクションフレームワークを提供しました。
• 拡張：Tugcan Topaloglu - ネットワーキング、3D/2D レンダリング、UI コントロール、オーディオエフェクト、アニメーションツリー、ファイル I/O、ランタイムコード実行、ノード操作、シグナル、プロジェクト作成、カメラ制御、物理演算、包括的な型変換を網羅する 157 個のツールに拡張しました。