Godot MCP

Godot MCP

AI アシスタントとGodotゲームエンジンをシームレスに連携させる、包括的なModel Context Protocol（MCP）サーバーです。

目次

• Godot MCPとは？
• 機能
• 要件
• インストール
• 設定
• APIリファレンス
• プロジェクトアーキテクチャ
• 使用例
• 読み取り専用モード
• トラブルシューティング
• よくある質問
• コントリビューション
• ライセンス

Godot MCPとは？

Godot MCPは、標準化されたModel Context Protocolインターフェースを提供し、AIアシスタントとGodotゲームエンジンの間をつなぎます。この強力な連携により、Claude、Cursor、ClineなどのAIアシスタントが、包括的なツールセットを通じてGodotプロジェクトを直接操作できます。

主な利点

• Godotとの直接連携：エディターの起動、プロジェクトの実行、デバッグ出力のプログラムによる取得が可能です
• シーン管理：AIコマンドを通じてGodotのシーンを作成、変更、管理できます
• リアルタイムのフィードバック：AIアシスタントが実際のGodotの出力やエラーを確認できるため、より適切な支援が可能です
• クロスプラットフォーム対応：Windows、macOS、Linuxでシームレスに動作します
• 安全な操作：プロジェクトを安全に分析できる、任意の読み取り専用モードを備えています
• 設定不要：Godotを自動検出し、必要に応じて手動で指定することもできます

仕組み

このサーバーはAIアシスタントとGodotの間のミドルウェア層として機能し、自然言語のコマンドを具体的なGodot操作に変換します。AIに「スプライト付きのプレイヤーシーンを作成して」と頼むと、MCPサーバーは次の処理を行います。

1. リクエストとプロジェクト構造を検証します
2. 適切なGodot操作を実行します
3. 成功またはエラーの詳細なフィードバックを返します
4. AIが結果を理解し、応答できるようにします

この仕組みによって、AIアシスタントが実際のGodotの動作から学習する強力なフィードバックループが生まれ、より正確なコード生成とデバッグ支援が可能になります。

機能

コアプロジェクト管理

• 🚀 Godotエディターの起動：指定したプロジェクトのGodotエディターを開きます
• ▶️ Godotプロジェクトの実行：リアルタイムで出力を取得しながら、プロジェクトをデバッグモードで実行します
• 🛑 実行の制御：Godotプロジェクトをプログラムから起動および停止します
• 📊 デバッグ出力の取得：包括的なコンソール出力とエラーメッセージを取得します
• ℹ️ システム情報：インストールされているGodotのバージョンとプロジェクトのメタデータを取得します
• 📁 プロジェクトの検出：指定したディレクトリ内のGodotプロジェクトを検索して一覧表示します

高度なシーン管理

• 🎬 新しいシーンを作成：指定したルートノードタイプでシーンを生成します
• ➕ ノードを追加：カスタマイズ可能なプロパティを設定して、既存のシーンにノードを挿入します
• ✏️ ノードのプロパティを編集：位置、スケール、テクスチャ、その他のノード属性を変更します
• 🗑️ ノードを削除：不要なノードを削除してシーンを整理します
• 🖼️ スプライトを読み込む：テクスチャを Sprite2D ノードに自動的に読み込みます
• 🧱 MeshLibrary をエクスポート：3D シーンを GridMap 用の MeshLibrary リソースに変換します
• 💾 シーンのバリエーションを保存：シーンのコピーを作成し、シーンのバージョンを管理します

Godot 4.4+ の UID 管理

• 🔗 ファイル UID を取得：プロジェクトのリソースの一意の識別子を取得します
• 🔄 UID 参照を更新：プロジェクトのアップグレード中にリソースリンクを適切に維持します

セキュリティと安全性

• 🔒 読み取り専用モード：安全な環境での操作を分析のみに制限します
• ✅ パスの検証：プロジェクトとファイルのパスを包括的に検証します
• 🛡️ エラー処理：実行可能な提案を含む、堅牢なエラー報告を行います

要件

システム要件

• Godot Engine：バージョン 3.5+ または 4.0+（最新の安定版を推奨）
• Node.js & npm

AI アシスタントとの互換性

• Cline & Roo Code：自動承認設定に完全対応
• Cursor & VS Code：UI とプロジェクト固有の設定の両方に対応
• Claude Desktop：MCP サーバーとの連携に対応
• その他の MCP 対応ツール：Model Context Protocol に対応するあらゆるツール

インストール

クローンとビルド

# Clone the repository
git clone https://github.com/bradypp/godot-mcp.git
cd godot-mcp

# Install dependencies
npm install

# Build the project
npm run build

設定

オプション A：Cline の設定

Cline の MCP 設定ファイルに追加します：

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "false",
        "READ_ONLY": "false",
        "GODOT_PATH": "/path/to/godot"
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "edit_node",
        "remove_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

オプション B：Cursor の設定

UI での設定

1. Cursor Settings → Features → MCP を開きます
2. + Add New MCP Server をクリックします
3. 次のように設定します：
   • Name：godot
   • Type：command
   • Command：node /absolute/path/to/godot-mcp/build/index.js
4. Add をクリックし、サーバーリストを更新します

プロジェクト固有の設定

プロジェクトのルートに .cursor/mcp.json を作成します：

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

環境変数

変数	説明	デフォルト値	例
GODOT_PATH	Godot 実行ファイルのパス	自動検出	/usr/bin/godot4
DEBUG	詳細なログ記録を有効にする	false	true
READ_ONLY_MODE	操作を読み取り専用に制限する	false	true

API リファレンス

システムツール

get_godot_version

インストールされている Godot のバージョン情報を取得します。

パラメーター：なし

応答例：

{
  "version": "4.2.1.stable",
  "platform": "linux.x86_64"
}

プロジェクトツール

launch_editor

指定したプロジェクトの Godot エディターを起動します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリのパス

例：

{
  "projectPath": "/home/user/my-game"
}

run_project

Godot プロジェクトを実行し、出力を取得します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリのパス
• scene (string, optional)：実行する特定のシーン

例：

{
  "projectPath": "/home/user/my-game",
  "scene": "scenes/MainMenu.tscn"
}

list_projects

指定したディレクトリ内の Godot プロジェクトを検索します。

パラメーター：

• directory (string, required)：プロジェクトを検索するディレクトリ
• recursive (boolean, optional)：再帰的に検索するかどうか（デフォルト：false）

get_project_info

Godot プロジェクトの詳細なメタデータを取得します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリのパス

応答例：

{
  "name": "My Awesome Game",
  "path": "/home/user/my-awesome-game",
  "godotVersion": "4.2.1.stable.official",
  "structure": {
    "scenes": 12,
    "scripts": 8,
    "assets": 45,
    "other": 3
  }
}

シーン管理ツール

create_scene

Godot プロジェクトに新しいシーンを作成します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリのパス
• scenePath (string, required)：新しいシーンファイルのパス（プロジェクトからの相対パス）
• rootNodeType (string, optional)：ルートノードのタイプ（デフォルト："Node2D"）

例：

{
  "projectPath": "/home/user/my-game",
  "scenePath": "scenes/Player.tscn",
  "rootNodeType": "CharacterBody2D"
}

add_node

既存のシーンにノードを追加します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリへのパス
• scenePath (string, required)：シーンファイルへのパス（プロジェクトからの相対パス）
• nodeType (string, required)：追加するノードの種類（例：「Sprite2D」、「CollisionShape2D」）
• nodeName (string, required)：新しいノードの名前
• parentNodePath (string, optional)：親ノードへのパス（デフォルトはルート）
• properties (object, optional)：設定する追加のプロパティ

例：

{
  "projectPath": "/home/user/my-game",
  "scenePath": "scenes/Player.tscn",
  "nodeType": "Sprite2D",
  "nodeName": "PlayerSprite",
  "properties": {
    "position": { "x": 100, "y": 50 },
    "scale": { "x": 2.0, "y": 2.0 }
  }
}

edit_node

シーン内の既存ノードのプロパティを編集します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリへのパス
• scenePath (string, required)：シーンファイルへのパス（プロジェクトからの相対パス）
• nodePath (string, required)：編集するノードへのパス
• properties (object, required)：更新するプロパティ

例：

{
  "projectPath": "/home/user/my-game",
  "scenePath": "scenes/Player.tscn",
  "nodePath": "PlayerSprite",
  "properties": {
    "position": { "x": 200, "y": 100 },
    "modulate": { "r": 1.0, "g": 0.5, "b": 0.5, "a": 1.0 }
  }
}

remove_node

シーンからノードを削除します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリへのパス
• scenePath (string, required)：シーンファイルへのパス（プロジェクトからの相対パス）
• nodePath (string, required)：削除するノードへのパス

load_sprite

テクスチャを Sprite2D ノードに読み込みます。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリへのパス
• scenePath (string, required)：シーンファイルへのパス（プロジェクトからの相対パス）
• nodePath (string, required)：Sprite2D ノードへのパス
• texturePath (string, required)：テクスチャファイルへのパス（プロジェクトからの相対パス）

save_scene

シーンを保存します。必要に応じて、新しいバリアントとして保存できます。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリへのパス
• scenePath (string, required)：シーンファイルへのパス（プロジェクトからの相対パス）
• newPath (string, optional)：バリアントとして保存する新しいパス

デバッグツール

get_debug_output

実行中のプロジェクトから現在のデバッグ出力とエラーを取得します。

パラメーター：なし

stop_project

現在実行中の Godot プロジェクトを停止します。

パラメーター：なし

UID ツール（Godot 4.4+）

get_uid

Godot プロジェクト内の特定のファイルの UID を取得します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリへのパス
• filePath (string, required)：ファイルへのパス（プロジェクトからの相対パス）

update_project_uids

リソースを再保存して、プロジェクト内の UID 参照を更新します。

パラメーター：

• projectPath (string, required)：Godot プロジェクトディレクトリへのパス

プロジェクトアーキテクチャ

コアコンポーネント

Godot MCP サーバーは、保守性と拡張性を考慮したモジュール型アーキテクチャを採用しています。

src/
├── config/           # Configuration management
├── core/            # Core functionality
│   ├── GodotExecutor.ts      # Godot command execution
│   ├── PathManager.ts        # Path detection and validation
│   ├── ProcessManager.ts     # Process lifecycle management
│   └── ParameterNormalizer.ts # Input parameter handling
├── server/          # MCP server implementation
│   ├── GodotMCPServer.ts     # Main server class
│   └── types.ts              # Type definitions
├── tools/           # Tool implementations
│   ├── BaseToolHandler.ts    # Shared tool functionality
│   ├── ToolRegistry.ts       # Tool registration and filtering
│   ├── debug/               # Debug-related tools
│   ├── project/             # Project management tools
│   ├── scene/               # Scene manipulation tools
│   ├── system/              # System information tools
│   └── uid/                 # UID management tools
├── utils/           # Utility functions
└── scripts/         # Godot operation scripts

主な設計原則

1. モジュール型ツールシステム：各ツールは、それぞれ独自の定義とハンドラーを持つ独立した構成要素です
2. 設定の一元管理：環境変数と設定を1か所で管理します
3. 堅牢なエラー処理：実行可能な提案を含む包括的なエラー報告を行います
4. セキュリティ優先：読み取り専用モードと入力検証により、誤用を防ぎます
5. クロスプラットフォーム対応：必要に応じて OS 固有の処理を行う、プラットフォームに依存しない設計です

ツール登録システム

ツールは ToolRegistry に登録され、各ツールの機能を示すメタデータが付与されます。

export interface ToolRegistration {
  definition: ToolDefinition;
  handler: (args: any) => Promise<ToolResponse>;
  readOnly: boolean;
}

レジストリは現在のモード（読み取り専用またはフルアクセス）に基づいてツールを自動的にフィルタリングし、ツールの検出と実行のための統一インターフェースを提供します。

バンドルされた操作のアーキテクチャ

複雑な Godot 操作では、GDScript を一元的に使用します。

1. 単一のスクリプトファイル: すべての操作を godot_operations.gd に集約します
2. JSON によるパラメーターの受け渡し: 操作には構造化されたパラメーターを渡します
3. 一時ファイルなし: ファイルシステムのオーバーヘッドと、後処理の複雑さをなくします
4. 一貫したエラー処理: すべての操作で標準化されたエラー報告を行います

このアーキテクチャは、操作ごとに一時スクリプトを生成する場合と比べて、パフォーマンス、保守性、信頼性に優れています。

使用例

基本的なプロジェクトのワークフロー

"Launch the Godot editor for my project at /path/to/my-game"

"Run my Godot project and show me any errors"

"Get information about my project structure and settings"

シーンの作成と管理

"Create a new Player scene with a CharacterBody2D root node"

"Add a Sprite2D node called 'PlayerSprite' to my Player scene"

"Load the character texture 'textures/player.png' into the PlayerSprite node"

"Set the Player's position to (100, 50) and scale to 2x"

"Create a CollisionShape2D node as a child of the Player root"

高度なワークフロー

"Create a complete UI scene with buttons for Start Game, Settings, and Quit"

"Export my 3D level models as a MeshLibrary for use with GridMap"

"Analyze my project structure and suggest performance improvements"

"Debug this GDScript error and help me fix the character controller"

"Create a save system scene with file I/O nodes and data management"

読み取り専用モード

読み取り専用モードを使用すると、変更を加えずに Godot プロジェクトを安全に分析できます。CI/CD パイプライン、コードレビュー、教育環境、共有開発のシナリオに最適です。

読み取り専用モードを有効にする

READ_ONLY_MODE 環境変数を "true" に設定します。

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

使用可能なツールと制限されたツール

✅ 読み取り専用モードで使用可能

システムツール:

• get_godot_version: Godot のバージョン情報を取得します

プロジェクトツール:

• launch_editor: Godot エディターを起動します
• run_project: プロジェクトを実行して動作を分析します
• list_projects: ディレクトリ内のプロジェクトを検出します
• get_project_info: プロジェクトのメタデータを取得します

デバッグツール:

• get_debug_output: コンソール出力を取得します
• stop_project: 実行中のプロジェクトを停止します

UID ツール:

• get_uid: ファイルの UID を取得します（Godot 4.4 以降）

❌ 読み取り専用モードで制限

シーン変更ツール:

• create_scene: 新しいシーンを作成します
• add_node: シーンにノードを追加します
• edit_node: ノードのプロパティを変更します
• remove_node: シーンからノードを削除します
• load_sprite: テクスチャをノードに読み込みます
• export_mesh_library: MeshLibrary リソースをエクスポートします
• save_scene: シーンの変更を保存します

UID 変更ツール:

• update_project_uids: UID 参照を更新します

使用例

• 🔄 CI/CD パイプライン: 変更のリスクを伴わずにプロジェクトを自動分析します
• 👥 コードレビュー: チームで安全にプロジェクトを確認できます
• 📊 ドキュメント: 自動ドキュメント作成用にプロジェクト情報を抽出します
• 🔍 デバッグ: 変更のリスクを伴わずにプロジェクトの動作を分析します

トラブルシューティング

よくある問題と解決策

Godot が見つからない

エラー: Could not find a valid Godot executable path

解決策:

1. GODOT_PATH 環境変数を設定する:

   export GODOT_PATH="/path/to/godot"
   # or for Windows:
   set GODOT_PATH="C:\Program Files\Godot\godot.exe"
   

2. Godot のインストールを確認する:

   # Test if Godot is accessible
   godot --version
   # or try:
   godot4 --version
   

3. 一般的な Godot のパス:

   • Windows: C:\Program Files\Godot\godot.exe
   • macOS: /Applications/Godot.app/Contents/MacOS/Godot
   • Linux: /usr/bin/godot4 または /usr/local/bin/godot

接続の問題

エラー: MCP サーバーが応答しない、またはツールを利用できない

解決策:

1. 設定を変更した後、AI アシスタントを再起動します
2. デバッグモードを有効にしてサーバーログを確認します: "DEBUG": "true"
3. 設定パスが絶対パスで、正しいことを確認します
4. サーバーを手動でテストします:

   node /path/to/godot-mcp/build/index.js
   

プロジェクトパスが無効

エラー: Invalid project path または project.godot not found

解決策:

1. パスに project.godot が含まれていることを確認します:

   ls /path/to/project/project.godot
   

2. 可能な場合は絶対パスを使用します
3. プロジェクトディレクトリのファイル権限を確認します

ビルドの問題

エラー: ビルドが失敗する、または依存関係が不足している

解決策:

1. クリーンビルドする:

   npm run clean
   npm install
   npm run build
   

2. npm キャッシュをクリアする:

   npm cache clean --force
   

ヘルプを得る

ここに記載されていない問題が発生した場合:

1. DEBUG=true を設定してデバッグログを確認します
2. GitHub で既存の問題を検索します
3. 次の情報を含めて、詳細な問題報告を作成します:
   • オペレーティングシステムとバージョン
   • Node.js と Godot のバージョン
   • エラーメッセージ全文
   • 使用した設定
   • 問題を再現する手順

よくある質問

一般的な質問

Q: 対応している Godot のバージョンを教えてください。 A: Godot 3.5 以降およびすべての Godot 4.x バージョンに対応しています。UID 管理など、一部の機能には Godot 4.4 以降が必要です。

Q: Godot 3.x のプロジェクトでも使えますか？ A: はい。ほとんどの機能は Godot 3.5 以降で動作します。シーン管理とプロジェクト操作は完全にサポートされています。

Q: 本番環境のプロジェクトで使っても安全ですか？ A: はい。特に読み取り専用モードを有効にすると安全です。このサーバーには、包括的な検証機能とエラー処理が組み込まれています。

技術的な質問

Q: サーバーは Godot のインストール先をどのように検出しますか？ A: サーバーは、各プラットフォームで一般的なインストール先を確認します。GODOT_PATH 環境変数を設定すると、検出先を上書きできます。

Q: サーバーのインスタンスを複数起動できますか？ A: はい。各インスタンスは独立して動作します。複数のプロジェクトを同時に扱う場合に便利です。

Q: 操作中に Godot がクラッシュした場合はどうなりますか？ A: サーバーがプロセスの異常終了を検出し、解決方法の提案を含む適切なエラーメッセージを返します。

Q: 操作中に一時ファイルは作成されますか？ A: いいえ。サーバーはバンドルされた GDScript 方式を採用しており、パフォーマンスとセキュリティを高めるため、一時ファイルの作成を回避します。

AI アシスタントとの連携

Q: このサーバーはどの AI アシスタントに対応していますか？ A: Cline、Roo Code、Cursor、VS Code、Claude Desktop など、Model Context Protocol に対応するあらゆる AI アシスタントで利用できます。

Q: 利用可能なツールをカスタマイズできますか？ A: はい。autoApprove 設定を使うか、カスタムビルドのツールレジストリを変更できます。

Q: 連携が機能しているかどうかは、どうすればわかりますか？ A: AI アシスタントから利用可能なツールを一覧表示して実行できれば、連携は機能しています。デバッグモードを有効にすると、操作ログの詳細を確認できます。

開発に関する質問

Q: サーバーにカスタムツールを追加できますか？ A: はい。モジュール式のアーキテクチャにより、新しいツールを簡単に追加できます。開発ガイドラインについては、CONTRIBUTING.md をご覧ください。

Q: プロジェクトに貢献するにはどうすればよいですか？ A: リポジトリをフォークし、変更を加えて、プルリクエストを送信してください。既存のコードスタイルに従い、テストを追加してください。

Q: このサーバーは他のゲームエンジンにも拡張できますか？ A: MCP アーキテクチャはエンジンに依存しませんが、この実装は Godot 専用に設計されています。他のエンジン向けにも同様のサーバーを作成できます。

貢献

Godot MCP の改善にご協力いただける方を歓迎します。以下の項目については、CONTRIBUTING.md のガイドをご覧ください。

• 開発環境のセットアップ手順
• コードスタイルのガイドライン
• テストの手順
• プルリクエストの手順
• Issue の報告に関するガイドライン

貢献者向けクイックスタート

# Fork and clone the repository
git clone https://github.com/your-username/godot-mcp.git
cd godot-mcp

# Install dependencies
npm install

# Start development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build

ライセンス

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

クレジット

このプロジェクトは、当初 Coding-Solo/godot-mcp をフォークして作成されました。

サポート

• 🐛 バグ報告：GitHub Issues
• 💡 機能リクエスト：GitHub Discussions
• 📖 ドキュメント：この README とインラインのコードドキュメント
• 💬 コミュニティ：Godot MCP と AI 支援開発についてのディスカッションにご参加ください

---

Godot と AI 開発のコミュニティのために、❤️ を込めて開発されました