Godot MCP

godot-mcp — Godot 4 向け純粋な Python 製 FastMCP サーバー

Godot 4 向けの Node.js 不要な Model Context Protocol サーバーです。 Coding-Solo/godot-mcp と youichi-uda/godot-mcp-pro を、公式の FastMCP フレームワークを使って純粋な Python に移植しました。uvx を使って、極めて少ない RAM で実行できます。

クイックスタート

手動でファイルをクローンしたり、仮想環境を設定したりすることなく、uvx を使ってマシン上のどこからでも標準入出力（stdio）経由でこのサーバーをすぐに呼び出せます。

# Run globally via uvx from PyPI (Bypasses local setup completely)
GODOT_PATH=/path/to/godot4 uvx --from godot-mcp-uvx godot-mcp

# Local development installation (For active contributors)
git clone https://github.com/jxlee007/godot_mcp
cd godot_mcp
uv tool install --editable .

MCP クライアントの設定

この構成設定ブロックを、グローバルなクライアント設定プロファイル（例：~/.gemini/antigravity-cli/settings.json または Claude ／ Cline の設定）に直接追加してください。

{
  "mcpServers": {
    "godot_render": {
      "command": "uvx",
      "args": [
        "--from",
        "godot-mcp-uvx",
        "godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "/path/to/godot4",
        "DEBUG": "false"
      }
    }
  }
}

環境変数

変数	説明
GODOT_PATH	Godot 4 実行ファイルへのパス（未設定の場合は自動検出）
DEBUG	"true" にすると、詳細な stderr ログを有効にします

ツール（全28種類）

コアランタイム（14種類）

ツール	説明
get_godot_version	インストール済みの Godot バージョンを返します
launch_editor	プロジェクトの Godot エディターを開きます
run_project	プロジェクトをデバッグモードで実行し、出力を取得します
get_debug_output	実行中のプロジェクトの stdout／stderr を読み取ります
stop_project	実行中のプロジェクトを終了し、最終出力を返します
list_projects	ディレクトリ内の Godot プロジェクトを検索します
get_project_info	メタデータ、ファイル数、バージョンを取得します
create_scene	GDScript を使って新しい .tscn ファイルを作成します
add_node	既存のシーンにノードを追加します
load_sprite	Sprite2D／TextureRect にテクスチャを読み込みます
export_mesh_library	.tscn を MeshLibrary .res としてエクスポートします
save_scene	シーンファイルを保存または別名で保存します
get_uid	Godot 4.4 以降のリソースの UID を取得します
update_project_uids	すべてのリソースを再保存して UID を再生成します

アニメーションテキストパイプライン（4種類）

ツール	説明
quantize_animation_keyframes	タイムスタンプを一定の fps 間隔に丸めます（アニメ風の 12／24 fps）
set_animation_interpolation_mode	イージングを一括で切り替えます：linear、cubic、nearest／stepped
stitch_animation_library	外部の .glb／.tres クリップをマスター AnimationLibrary に統合します
generate_track_filter	上半身／下半身を分離する AnimationNodeBlendFilter を生成します

AnimationTree のブループリント作成（3種類）

ツール	説明
generate_state_machine	AnimationNodeStateMachine を .tscn ファイルに挿入します
compile_state_transitions	条件付きの遷移矢印を書き込みます
calculate_blend_space_2d	方向移動用の 2D ブレンドスペースを生成します

カメラとシネマティック（3種類）

ツール	説明
generate_bezier_camera_path	張力を調整できる Catmull-Rom ベジェ Path3D ＋ PathFollow3D ＋ Camera3D を生成します
inject_lookat_tracking	Camera3D 用の LookAt トラッキング GDScript を生成します
build_camera_switcher_timeline	タイムスタンプに基づいて Camera3D.current を切り替える Animation を書き込みます

NPR マテリアルとシェーダー（2種類）

ツール	説明
batch_shader_uniforms	すべての .tres ファイル内の shader_parameter/* を一括で上書きします
remap_texture_channels	テクスチャをマテリアルのプロパティスロットに割り当てます

パイプラインの自動化（2種類）

ツール	説明
toggle_movie_maker	Movie Maker モードを有効化／無効化するよう project.godot を編集します
run_headless_diagnostics	Godot CLI を使ってインポート、UID、シェーダーのエントリーポイントを検証します

アーキテクチャ

src/godot_mcp/
├── __init__.py
├── server.py              # FastMCP app — all 28 tools
└── scripts/
    └── godot_operations.gd  # Bundled GDScript engine (preserved untouched)

2 つの動作モード：

1. サブプロセスブリッジ — コアの 14 個のツールは、subprocess.run() を介してヘッドレスで godot_operations.gd を実行します
2. テキスト操作 — pro-port の 14 個のツールは、Python 標準ライブラリの re のみを使用して、.tscn、.tres、project.godot ファイルをプレーンテキストとして解析・書き込みます

要件

• Python 3.10 以降
• Godot 4.x がインストールされていること（GODOT_PATH を設定するか、$PATH に含めてください）
• uv または pip

ライセンス

MIT