Godot MCP Unified - AI + Godot アーキテクチャ

未来の自分へのドキュメント - Godotで自然言語コーディングを行うための完全設定

英語で読む

全体アーキテクチャ

                    +------------------+
                    |   Claude Code    |
                    |    (VS Code)     |
                    +--------+---------+
                             |
                             v
+----------------+  +--------+---------+  +------------------+
| Claude Desktop |->|                  |<-| ollmcp (Ollama)  |
|   (Anthropic)  |  | godot-mcp-unified|  | qwen2.5-coder:7b |
+----------------+  |   (ce serveur)   |  +------------------+
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
              v                             v
     +--------+---------+          +--------+---------+
     |  Godot CLI       |          |  Plugin WebSocket|
     |  (--headless)    |          |  (addons/godot_  |
     |  Fallback mode   |          |   mcp/) Port 6505|
     +------------------+          +------------------+
              |                             |
              +-------------+---------------+
                            |
                            v
                   +--------+---------+
                   |  Godot Engine    |
                   |    4.5.1         |
                   +------------------+

Godotとの通信

サーバーはプラグインが接続されているかを自動検出し、最適なモードを使用します。

このサーバーでできること

Godotのあらゆる操作を自然言語で実行可能（83ツール + 20リソース + 20プロンプト）：

インストール（完了済み）

インストール済み前提条件

• Node.js (MCPサーバー用)

• Godot 4.5.1: C:\Dev\Godot_v4.5.1-stable_win64.exe\Godot_v4.5.1-stable_win64_console.exe

• uv (モダンなPythonマネージャー)

• ollmcp (Ollama <-> MCPブリッジ)

このサーバー

cd C:\Dev\godot-mcp-unified
npm install
npm run build

設定

Claude Desktop (C:\Users\pierr\AppData\Roaming\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

VS Code / Claude Code (Godotプロジェクト内の .vscode/mcp.json)

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

Ollama (ollmcp経由)

# Lancer le bridge
ollmcp --model qwen2.5-coder:7b C:\Dev\godot-mcp-unified\build\index.js

# Ou via ollama-gateway (port 3010)

利用可能なOllamaモデル

注意: -chessモデルはチェスをプレイするためのものではなく、FFEシステムプロンプトを使用したchess-app開発用のカスタムアシスタントです。

APIリファレンス (83ツール + 20リソース + 20プロンプト)

統計

Primitives MCP:
  Tools:     83/83   ████████████████████ 100%
  Resources: 20/20   ████████████████████ 100%
  Prompts:   20/20   ████████████████████ 100%

Qualite:
  Tests:    3170+    ████████████████████ 100% pass (69 suites)
  Coverage:  85%     █████████████████░░░  85%

Bridge Plugin:
  Avec bridge:  47 outils (utilisent WebSocket si plugin actif)
  Sans bridge:  35 outils (CLI/file I/O uniquement)

プロジェクト管理 (14ツール)

• launch_editor - Godotエディタを開く

• run_project - プロジェクトを実行

• stop_project - プロジェクトを停止

• list_projects - フォルダ内のプロジェクトをリスト表示

• get_project_info - プロジェクト情報を取得

• get_godot_version - Godotのバージョンを取得

• get_project_settings - プロジェクト設定を読み込む

• set_project_setting - 設定を変更する

• manage_input_actions - 入力アクションを管理

• manage_autoloads - オートロードを管理

• validate_project - プロジェクト構造を検証

• convert_project - Godot 3から4へプロジェクトを変換

• validate_conversion - 変換を検証

• generate_docs - GDScriptドキュメントを生成

シーン管理 (15ツール)

• create_scene - 新規シーンを作成

• add_node - ノードを追加

• edit_node - ノードのプロパティを編集

• remove_node - ノードを削除

• rename_node - ノード名を変更

• move_node - ノードを移動（親変更）

• duplicate_node - ノードを複製

• load_sprite - テクスチャを読み込む

• save_scene - シーンを保存

• instance_scene - シーンをインスタンス化

• list_scenes - シーンをリスト表示

• get_node_tree - シーンツリーを取得

• connect_signal - シグナルを接続

• manage_groups - ノードグループを管理

• export_mesh_library - MeshLibraryとしてエクスポート

GDScript (7ツール)

• list_scripts - プロジェクト内の全.gdファイルをリスト表示

• read_script - スクリプトの内容を読み込む

• write_script - スクリプトを作成/編集

• delete_script - スクリプトを削除

• attach_script - ノードにスクリプトをアタッチ

• detach_script - ノードからスクリプトをデタッチ

• get_script_errors - コンパイルエラーを取得

アニメーション (7ツール)

• create_animation_player - AnimationPlayerを作成

• add_animation - アニメーションを追加

• add_animation_track - トラックを追加 (値、位置、回転など)

• set_keyframe - トランジション/イージング付きでキーフレームを設定

• create_animation_tree - AnimationTreeを作成

• setup_state_machine - ステートマシンを設定

• blend_animations - アニメーションブレンドを設定

物理演算 (3ツール)

• create_collision_shape - CollisionShape2D/3Dを作成

• setup_rigidbody - RigidBodyを設定 (質量、重力)

• configure_physics_layers - 2D/3D物理レイヤーに名前を付ける

TileMap (5ツール)

• create_tileset - タイルサイズを指定してTileSetを作成

• create_tilemap_layer - TileMapLayerを作成

• set_tile - タイルを配置

• paint_tiles - タイルをバッチで描画

• import_ldtk_level - LDtkレベルをインポート

オーディオ (3ツール)

• create_audio_bus - オーディオバスを作成

• setup_audio_player - AudioStreamPlayerを設定

• add_audio_effect - エフェクトを追加 (リバーブ、ディレイ、EQ)

シェーダー (2ツール)

• create_shader - .gdshaderファイルを作成

• create_shader_material - ShaderMaterialを作成

ナビゲーション (2ツール)

• create_navigation_region - NavigationRegion2D/3Dを作成

• bake_navigation_mesh - ナビメッシュをベイク

パーティクル (2ツール)

• create_gpu_particles - GPUParticles2D/3Dを作成

• create_particle_material - ParticleProcessMaterialを作成

UI (2ツール)

• create_ui_container - コンテナを作成 (VBox, HBox, Gridなど)

• create_control - コントロールを作成 (Button, Labelなど)

ライティング (3ツール)

• create_light - Light2D/3Dを作成 (Directional, Omni, Spot)

• setup_environment - 環境を設定 (フォグ、グロー、SSAO)

• setup_lightmapper - LightmapGIとベイクを設定

アセット (3ツール)

• list_assets - アセットをリスト表示 (画像、オーディオ、モデル)

• import_asset - 外部ファイルをインポート

• reimport_assets - 強制再インポート

エクスポート (3ツール)

• export_project - プロジェクトをエクスポート

• export_pack - PCKのみエクスポート

• list_export_presets - エクスポートプリセットをリスト表示

バッチ操作 (1ツール)

• batch_operations - 複数のMCPツールを順番に実行

デバッグ (5ツール)

• get_debug_output - コンソール出力を取得

• start_debug_stream - デバッグWebSocketサーバーを開始

• stop_debug_stream - WebSocketサーバーを停止

• get_debug_stream_status - サーバーの状態を取得

• take_screenshot - スクリーンショットを撮影

UID (Godot 4.4+) (2ツール)

• get_uid - ファイルのUIDを取得

• update_project_uids - 参照を更新

システム (2ツール)

• system_health - システムの健全性チェック

• get_godot_version - Godotのバージョンを取得

使用例

プレイヤーキャラクターの作成

"Cree une scene Player.tscn avec un CharacterBody2D comme root,
ajoute un Sprite2D nomme 'Sprite' et un CollisionShape2D nomme 'Collision'"

プロジェクトのデバッグ

"Lance mon projet Godot et montre-moi les erreurs dans la console"

既存シーンの編集

"Dans la scene Player.tscn, change la position du Sprite a (100, 50)
et sa scale a 2x"

Godotプロジェクト構造

C:\Dev\
├── jdvlh-godot-client\     <- Projet principal (pas de remote git configure!)
│   ├── project.godot
│   ├── .vscode\mcp.json    <- Config MCP pour ce projet
│   └── addons\godot_mcp\   <- Plugin MCP copie
│
├── jdvlh-godot\            <- Projet vide (a garder pour tests)
│
└── GodotDynamicDialog\     <- Fork de dynamic-dialog

コードの起源

このサーバーは、3つのオープンソースプロジェクトの機能を統合しています：

注意: GDAI MCPも存在しますが、有料（$19）です。

マシンスペック

• CPU: Ryzen 5 5600H

• RAM: 16 GB

• GPU: AMD Radeon (内蔵) - CUDAなし

• 最適な量子化: Q4_K_M (品質とパフォーマンスのスイートスポット)

トラブルシューティング

サーバーが起動しない

cd C:\Dev\godot-mcp-unified
npm run build

Godotが見つからない

GODOT_PATHが正しい実行ファイル（ログを確認できるコンソール版）を指しているか確認してください。

Claude Desktopがツールを認識しない

設定変更後、Claude Desktopを再起動してください。

便利なコマンド

# Rebuild le serveur
cd C:\Dev\godot-mcp-unified && npm run build

# Tester avec l'inspecteur MCP
npm run inspector

# Lister les modeles Ollama
ollama list

# Supprimer un modele Ollama
ollama rm nom_modele

TODO

• [ ] jdvlh-godot-client用のgitリモートを設定

• [ ] 重複するOllamaモデル（qwen2.5, gemma2, llama3.2, deepseek-coder-v2）を整理

• [ ] 新規プロジェクトでの完全な統合テスト

最終更新日: 2026年2月11日 godot-mcp-unified v0.9.0 - 83ツール + 20リソース + 20プロンプト カバレッジ: 85% | テスト: 3170+ (69スイート) | ISO 25010/29119/5055/27001準拠