godot

Godot MCP Server

Godot 4.x のゲーム開発向けの包括的な FastMCP サーバーです。AI 支援ワークフロー向けのツールを提供します。プロジェクト管理、ファイル操作、アセットの検索、GDScript 開発、オプションの Godot 実行に対応しています。

コントリビューション · セキュリティ

セキュリティモデル： Godot プロジェクト、ファイルへの書き込み、Asset Library からのダウンロードはすべて、お使いのマシン上の単一の ワークスペースディレクトリ（デフォルトは ~/godot-games）に制限されます。サーバーはこのディレクトリツリー外のパスを拒否します。ワークスペースの設定を参照してください。

コード実行： godot_run_game と godot_execute_script を使用するには、サーバー環境で GODOT_MCP_ALLOW_GODOT_EXEC を設定する必要があります。付属の MCP JSON 設定では、コピーして貼り付けた後にこれらのツールを使えるよう、値に 1 を設定しています。python godot_mcp_server.py を、この環境変数を設定せずに実行した場合、環境変数をエクスポートするまでコード実行は無効のままです。IDE へのインストールを制限するには、この変数を削除するか、0 に設定してください。Godot の実行（環境変数）を参照してください。

HTTP トランスポート： 0.0.0.0 または :: にバインドすると、すべてのネットワークインターフェースで MCP サーバーが公開されます。ファイアウォールまたは VPN を使用しない場合は、127.0.0.1 を推奨します。

シンボリックリンク： GODOT_MCP_ROOT はシンボリックリンクをたどって解決されます。自身が管理する実際のディレクトリを指定してください。

機能

プロジェクト管理

• Godot プロジェクト（project.godot）を自動検出し、ワークスペース内のすべてのプロジェクトを一覧表示します（godot_list_projects）
• ワークスペース内に新しいプロジェクトを作成します（godot_create_project）
• プロジェクト設定と構成を解析し、オートロードとエディタープラグインの状態を一覧表示します（プラグインは読み取り専用）
• 変更後にプロジェクトキャッシュを更新します

ファイル操作

• シーン（.tscn）、スクリプト（.gd）、リソース（.tres）の読み書き
• テンプレートから新しいスクリプト、シーン、リソースを作成
• 内容を置き換えて既存のファイルを編集
• シーンとスクリプトの構文を検証

コード生成

• CharacterBody2D/3D の移動コントローラー
• ステートマシンのパターン
• カスタムリソース
• シグナルとエクスポートを備えたノードスクリプト

アセット管理

• 拡張子、パターン、glob によるアセットの検索
• 未使用のアセットを検索
• 正規表現でファイルの内容を検索
• Godot Asset Library から検索してダウンロード
• GitHub で Godot リポジトリを閲覧

ランタイム連携

• Godot 実行ファイルを検索
• Godot のバージョンを確認
• ヘッドレスでゲームを実行
• GDScript コードを実行
• Godot のログを読み取り
• ファイル監視の設定

インストール

# From PyPI-style editable install (recommended for contributors)
pip install -e .

# Or minimal deps only
pip install -r requirements.txt

コンソールエントリーポイント（pip install -e . の後）：godot-mcp-server（python godot_mcp_server.py と同じです）。

ワークスペースのセットアップ（必須）

MCP サーバーは、1 つのルートフォルダー内にある Godot プロジェクトのみを操作します。これにより、アシスタントがシステム上の任意のパスを読み書きするのを防ぎます。

1. 既定のフォルダーを作成します（マシンごとに 1 回）：

   mkdir -p ~/godot-games
   

2. すべての Godot ゲームをその中に配置します — 各ゲームは project.godot を含む独自のサブディレクトリに配置します。例：

   ~/godot-games/
     my-platformer/     ← open this folder in your editor
       project.godot
       ...
     another-game/
       project.godot
   

3. MCP プロセスが現在の作業ディレクトリから project.godot を検出できるよう、IDE ワークスペースを ~/godot-games/.../your-game（または ~/godot-games 配下の親フォルダー）内で開きます。

4. カスタムの場所： サーバーを起動する前に、絶対パスを設定します。

   export GODOT_MCP_ROOT="/path/to/your/godot-games"
   python godot_mcp_server.py
   

   Cursor／Claude／その他の MCP 設定で、env を追加します。

   "env": {
     "GODOT_MCP_ROOT": "/path/to/your/godot-games"
   }
   

   設定されていない場合、既定値は $HOME/godot-games です。サーバーは起動時に、そのディレクトリが存在しなければ作成します。

5. 実行時に確認： godot_get_workspace ツールを呼び出すか、project://workspace リソースを読み取り、アクティブなワークスペースのパスを確認します。

ツールがプロジェクトが見つからないと報告する場合、cwd がワークスペースの外にあるか、project_path が GODOT_MCP_ROOT の外を指している可能性があります。

Godot の実行（環境）

ゲームの実行や GDScript の実行は、ユーザー権限でコードを実行します（ターミナルから Godot を起動する場合と同じです）。サーバーは、GODOT_MCP_ALLOW_GODOT_EXEC が許可された「オン」の値に設定されている場合にのみ、godot_run_game／godot_execute_script を有効にします。

同梱の設定（既定で許可）： このリポジトリ内のすべてのサンプル JSON（mcp_config.json、mcp_config.cursor.json など）には、次の設定が含まれています。

"env": {
  "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}

そのため、これらの設定を IDE にコピーすれば、追加の手順なしで実行が許可されます。他のキー（例：GODOT_MCP_ROOT）は、同じ env オブジェクトに統合してください。

MCP 設定を使わない CLI： python godot_mcp_server.py を実行しても、この変数は設定されません。export GODOT_MCP_ALLOW_GODOT_EXEC=1 を実行するか、ラッパースクリプトを使うまで、実行ツールはブロックされたままです。

より厳格な設定： env から GODOT_MCP_ALLOW_GODOT_EXEC を削除するか、0／false／no／off に設定してから、MCP クライアントを再起動します。

許可される「オン」の値：1、true、yes、on（大文字と小文字は区別されません）。godot_get_workspace を呼び出し、godot_exec_allowed を確認してください。

使い方

CLI（stdio - Claude Code/Cursor 用）

python godot_mcp_server.py

HTTP サーバー

python godot_mcp_server.py --transport http --port 8765

設定

既定の ~/godot-games を使用しない場合は、MCP サーバーの env に GODOT_MCP_ROOT を設定します。ワークスペースのセットアップを参照してください。以下の同梱スニペットには GODOT_MCP_ALLOW_GODOT_EXEC が含まれています。Godot の実行（環境）を参照してください。

サーバーへのパス： 例では、MCP プロセスの作業ディレクトリがスクリプトを含むフォルダー（例：このリポジトリをクローンしたフォルダー）であることを前提に、"args": ["godot_mcp_server.py"] を使用しています。サーバーの起動に失敗する場合は、godot_mcp_server.py の絶対パスを指定してください。

エディターにインストールする

セクションを展開し、JSON をツールが指定するファイルに貼り付けます。同じ godot サーバーブロックがリポジトリ内の mcp_config.*.json にあり、コピーして貼り付けられます。

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "python", "C:\\path\\to\\godot-mcp-server\\godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["/absolute/path/to/godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development - project, scenes, scripts, assets, runtime"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game dev - project, scenes, scripts, assets, runtime"
    }
  }
}

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server - file ops, asset management, runtime integration"
    }
  }
}

制限事項（DoS／不正利用）

• 正規表現検索（godot_search_content）： パターンの長さと検索結果のリストには上限があります。2 MiB を超えるファイルはスキップされます。悪意のある正規表現は処理に時間がかかる可能性があるため、シンプルなパターンを使用してください。
• アセットの ZIP ダウンロード： 展開前に、ダウンロードサイズ、ファイルごとの展開後サイズ、展開後の合計サイズ、ファイル数に上限が適用されます（godot_mcp_server.py の先頭付近にある定数を参照）。
• Asset Library ID： godot_get_asset_info／godot_download_asset の asset_id は、数字のみである必要があります。

HTTP モード（リモート）

特に理由がない限り、ループバックを使用してください。

python godot_mcp_server.py --transport http --host 127.0.0.1 --port 8765

すべてのインターフェースにバインドすると（--host 0.0.0.0）、警告がログに記録され、このサーバーでは認証なしで MCP が LAN に公開されます。

次に、command の代わりに serverUrl を使用します。

{
  "mcpServers": {
    "godot": {
      "serverUrl": "http://localhost:8765/mcp"
    }
  }
}

godot_mcp_server.py に 40 個の MCP ツールが登録されています（@mcp.tool を検索してください）。概要：

エディタープラグイン： このサーバーは、開いているエディターとの競合を避けるため、project.godot の [editor_plugins] に書き込みません。上記のツールでアドオンをインストールし、Godot の Project Settings → Plugins でユーザーがプラグインを有効にします。有効化を確認するには godot_list_editor_plugins を使用してください。

リソース

例

プラットフォーマーのプレイヤーを作成

# Using template
create_code_template("character_body_2d", "Player")

アセットを検索

# All PNG files
find_assets([".png", ".jpg"])

# Unused assets
find_unused_files()

Asset Library を検索

search_assetlib("platformer")
# => [{title: "PlatformerController2D", ...}]

get_asset_info("1062")
# => {title, author, description, license, download_url}

ゲームをヘッドレスで実行

GODOT_MCP_ALLOW_GODOT_EXEC が必要です（同梱されている MCP JSON 設定に含まれています）。

run_game(headless=True, quit_after_seconds=30)

必要条件

• Python 3.10+
• 依存関係：fastmcp、urllib3（pyproject.toml を参照）

開発

pip install -e ".[dev]"
ruff check godot_mcp_server.py tests
pytest

継続的インテグレーションは Python 3.10–3.14 で実行されます（.github/workflows/ci.yml を参照）。Dependabot は pip と GitHub Actions の PR を毎週作成します。

任意：pip install pre-commit && pre-commit install を実行すると、.pre-commit-config.yaml が使用されます。

GitHub に公開

1. GitHub に空のリポジトリを作成します（README／ライセンスをローカルにすでに用意している場合は、それらを含めないでください）。例：godot-mcp-server。
2. リモートを追加してプッシュします：

cd /path/to/godot-mcp-server
git remote add origin https://github.com/YOUR_USER/godot-mcp-server.git
git push -u origin main

または、GitHub CLI を使用します：gh repo create godot-mcp-server --public --source=. --remote=origin --push

最初のプッシュ後は、プッシュと PR のたびに CI が実行されます。別のアカウントまたは組織を使用する場合は、README のバッジ URL 内の sterion66 を置き換えてください。

ライセンス

MIT