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ログを読む

• ファイルウォッチャー設定

Related MCP server: Godot MCP

インストール

# 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. IDEワークスペースを ~/godot-games/.../your-game（または ~/godot-games 配下の親フォルダ）で開きます。これにより、MCPプロセスが現在の作業ディレクトリから project.godot を検出できます。

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の実行（環境）を参照してください。

サーバーへのパス: 例では "args": ["godot_mcp_server.py"] を使用しており、MCPプロセスがスクリプトを含むフォルダを作業ディレクトリとして実行されることを前提としています（例: このリポジトリをクローンした場合）。サーバーが起動しない場合は、マシン上の godot_mcp_server.py への絶対パスに置き換えてください。

エディタにインストール

セクションを展開して、ツールが期待するファイルにJSONを貼り付けます。同じ godot サーバーブロックは、コピー＆ペースト用に mcp_config.*.json としてリポジトリにあります。

macOS / Linux（プロジェクトまたはユーザー設定） — 設定 → MCP → 新しいグローバルMCPサーバーを追加 またはプロジェクトルートに .cursor/mcp.json を作成:

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

Windows — MCPホストのPATHに python がない場合は、ランチャーまたは python.exe への完全パスを使用し、args には絶対パスを推奨します:

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

~/godot-games を使用しない場合は、GODOT_MCP_ROOT を env にマージしてください（ワークスペースの設定を参照）。

VS Codeビルドが提供するMCP / エージェント設定を使用します（バージョンと拡張機能に応じて、多くの場合設定 → MCP またはプロジェクトの .vscode/mcp.json）。Cursorと同じ構造を貼り付けます:

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

ワークスペースフォルダがリポジトリルートでない場合は、args に絶対パスを使用します。

アプリ設定ファイルを編集します:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

保存後、Claude Desktopを再起動します。

~/.claude/settings.json にマージします（CLIがサポートしている場合は claude mcp add を使用 — claude mcp --help で確認してください）:

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

macOS / Linux: ~/.codeium/windsurf/mcp_config.json を編集するか、CMD+SHIFT+P → “Windsurf: Configure MCP Servers” を使用します。

{
  "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"
    }
  }
}

RooのMCP設定（プロジェクトまたはグローバル）に貼り付けます。上記と同じJSON形式です。リポジトリ内のコピー: roo_code_mcp.json。

{
  "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"
    }
  }
}

最小限のstdio設定 — このリポジトリの mcp_config.json と同じ:

{
  "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を超えるファイルはスキップされます。悪意のある正規表現は依然として高コストになる可能性があります—パターンはシンプルに保ってください。

• Asset 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"
    }
  }
}

同じプロジェクトには1つのトランスポート（stdio または HTTP）だけを実行します。両方を同時に実行すると、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()

アセットライブラリを検索

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

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

ライセンス

MIT