/ README.md
README.md
1 # Godot MCP Pro 2 3 Premium MCP (Model Context Protocol) server for AI-powered Godot game development. Connects AI assistants like Claude directly to your Godot editor with **172 powerful tools**. 4 5 ## Architecture 6 7 ``` 8 AI Assistant ←—stdio/MCP—→ Node.js Server ←—WebSocket:6505—→ Godot Editor Plugin 9 ``` 10 11 - **Real-time**: WebSocket connection means instant feedback, no file polling 12 - **Editor Integration**: Full access to Godot's editor API, UndoRedo system, and scene tree 13 - **JSON-RPC 2.0**: Standard protocol with proper error codes and suggestions 14 15 ## What's in this repo 16 17 > ⚠️ **This public repo only contains the free Godot addon/plugin.** The MCP server (Node.js, required to connect AI assistants) is distributed as part of the paid package — **one-time purchase**, lifetime updates: 18 > 19 > - **Buy Me a Coffee**: <https://buymeacoffee.com/y1uda/extras> 20 > - **itch.io**: <https://y1uda.itch.io/godot-mcp-pro> 21 > 22 > The paid zip includes the addon, the `server/` directory with pre-built JavaScript, `INSTALL.md`, and AI-client instructions. If you cloned this repo and don't see a `server/` folder, **that's expected** — grab the full package from one of the links above. 23 24 ## Quick Start 25 26 ### 1. Install the Godot Plugin 27 28 Copy the `addons/godot_mcp/` folder into your Godot project's `addons/` directory. 29 30 Enable the plugin: **Project → Project Settings → Plugins → Godot MCP Pro → Enable** 31 32 ### 2. Install the MCP Server 33 34 > The `server/` directory is only included in the **full paid package** (see above). After downloading and extracting the zip, run: 35 36 ```bash 37 cd server 38 npm install 39 npm run build 40 ``` 41 42 ### 3. Configure Claude Code 43 44 Add to your `.mcp.json`: 45 46 ```json 47 { 48 "mcpServers": { 49 "godot-mcp-pro": { 50 "command": "node", 51 "args": ["/path/to/server/build/index.js"], 52 "env": { 53 "GODOT_MCP_PORT": "6505" 54 } 55 } 56 } 57 } 58 ``` 59 60 ### 4. Choose Your Mode 61 62 Godot MCP Pro offers four modes to fit any client's tool limit: 63 64 | Mode | Tools | Best For | 65 |------|-------|----------| 66 | **Full** (default) | 172 | Claude Code, Cline, VS Code Copilot, Cursor | 67 | **3D** (`--3d`) | 100 | Antigravity and other 100-tool-limit clients needing 3D | 68 | **Lite** (`--lite`) | 81 | Windsurf, JetBrains Junie, Gemini CLI | 69 | **Minimal** (`--minimal`) | 35 | OpenCode, local LLMs with small context | 70 71 ```json 72 { 73 "mcpServers": { 74 "godot-mcp-pro": { 75 "command": "node", 76 "args": ["/path/to/server/build/index.js", "--lite"] 77 } 78 } 79 } 80 ``` 81 82 Replace `--lite` with `--minimal` for the smallest footprint. 83 84 - **Lite** includes: project, scene, node, script, editor, input, runtime, and input_map tools. 85 - **Minimal** includes: 35 essential tools — project info, scene management, node CRUD, script editing, editor errors, input simulation, and runtime inspection. 86 87 ### 5. CLI Mode (Alternative to MCP) 88 89 For clients without MCP support, or when you want zero context overhead, use the CLI directly from a terminal/bash tool. The CLI requires the server to be built first (Step 2). 90 91 ```bash 92 # Top-level help — shows all command groups 93 node /path/to/server/build/cli.js --help 94 95 # Group help — shows commands in a group 96 node /path/to/server/build/cli.js node --help 97 98 # Command help — shows options for a command 99 node /path/to/server/build/cli.js node add --help 100 101 # Execute 102 node /path/to/server/build/cli.js project info 103 node /path/to/server/build/cli.js scene play 104 node /path/to/server/build/cli.js node add --type CharacterBody3D --name Player 105 ``` 106 107 Replace `/path/to/` with the actual path where you extracted the files. 108 109 The CLI connects directly to the Godot editor plugin via WebSocket. It requires: 110 - Godot editor running with the MCP plugin enabled 111 - Server built (`node build/setup.js install`) 112 - An available port in the 6510-6514 range 113 114 **Advantage**: LLMs discover capabilities progressively via `--help` instead of loading all tool definitions upfront. This works with any LLM client that has terminal access, regardless of tool count limits. 115 116 ### 6. Client Compatibility 117 118 | Client | Recommended Mode | Notes | 119 |--------|-----------------|-------| 120 | Claude Code | Full (default) | Deferred tool loading — minimal context cost | 121 | VS Code Copilot | Full | Virtual Tools auto-group tools | 122 | OpenAI Codex CLI | Full | MCPSearch defers overflow | 123 | Cline | Full | No hard limit; use `enabledTools` to whitelist | 124 | Roo Code | Full | No hard limit | 125 | Windsurf | Lite | 100 tool limit | 126 | JetBrains Junie | Lite | 100 tool limit | 127 | Gemini CLI | Lite | ~100 client limit; use `excludeTools` for finer control | 128 | Cursor | Full | Tool limit removed (Dynamic Context Discovery) | 129 | OpenCode | Minimal or CLI | Models degrade past ~40 tools | 130 | Local LLMs (LM Studio, etc.) | Minimal or CLI | Context window is the bottleneck | 131 132 ### 7. Use It 133 134 Open your Godot project with the plugin enabled, then use Claude Code to interact with the editor. 135 136 ## All 172 Tools 137 138 ### Project Tools (7) 139 | Tool | Description | 140 |------|-------------| 141 | `get_project_info` | Project metadata, version, viewport, autoloads | 142 | `get_filesystem_tree` | Recursive file tree with filtering | 143 | `search_files` | Fuzzy/glob file search | 144 | `get_project_settings` | Read project.godot settings | 145 | `set_project_setting` | Set project settings via editor API | 146 | `uid_to_project_path` | UID → res:// conversion | 147 | `project_path_to_uid` | res:// → UID conversion | 148 149 ### Scene Tools (9) 150 | Tool | Description | 151 |------|-------------| 152 | `get_scene_tree` | Live scene tree with hierarchy | 153 | `get_scene_file_content` | Raw .tscn file content | 154 | `create_scene` | Create new scene files | 155 | `open_scene` | Open scene in editor | 156 | `delete_scene` | Delete scene file | 157 | `add_scene_instance` | Instance scene as child node | 158 | `play_scene` | Run scene (main/current/custom) | 159 | `stop_scene` | Stop running scene | 160 | `save_scene` | Save current scene to disk | 161 162 ### Node Tools (14) 163 | Tool | Description | 164 |------|-------------| 165 | `add_node` | Add node with type and properties | 166 | `delete_node` | Delete node (with undo support) | 167 | `duplicate_node` | Duplicate node and children | 168 | `move_node` | Move/reparent node | 169 | `update_property` | Set any property (auto type parsing) | 170 | `get_node_properties` | Get all node properties | 171 | `add_resource` | Add Shape/Material/etc to node | 172 | `set_anchor_preset` | Set Control anchor preset | 173 | `rename_node` | Rename a node in the scene | 174 | `connect_signal` | Connect signal between nodes | 175 | `disconnect_signal` | Disconnect signal connection | 176 | `get_node_groups` | Get groups a node belongs to | 177 | `set_node_groups` | Set node group membership | 178 | `find_nodes_in_group` | Find all nodes in a group | 179 180 ### Script Tools (8) 181 | Tool | Description | 182 |------|-------------| 183 | `list_scripts` | List all scripts with class info | 184 | `read_script` | Read script content | 185 | `create_script` | Create new script with template | 186 | `edit_script` | Search/replace or full edit | 187 | `attach_script` | Attach script to node | 188 | `get_open_scripts` | List scripts open in editor | 189 | `validate_script` | Validate GDScript syntax | 190 | `search_in_files` | Search content in project files | 191 192 ### Editor Tools (9) 193 | Tool | Description | 194 |------|-------------| 195 | `get_editor_errors` | Get errors and stack traces | 196 | `get_editor_screenshot` | Capture editor viewport | 197 | `get_game_screenshot` | Capture running game | 198 | `execute_editor_script` | Run arbitrary GDScript in editor | 199 | `clear_output` | Clear output panel | 200 | `get_signals` | Get all signals of a node with connections | 201 | `reload_plugin` | Reload the MCP plugin (auto-reconnect) | 202 | `reload_project` | Rescan filesystem and reload scripts | 203 | `get_output_log` | Get output panel content | 204 205 ### Input Tools (7) 206 | Tool | Description | 207 |------|-------------| 208 | `simulate_key` | Simulate keyboard key press/release | 209 | `simulate_mouse_click` | Simulate mouse click at position | 210 | `simulate_mouse_move` | Simulate mouse movement | 211 | `simulate_action` | Simulate Godot Input Action | 212 | `simulate_sequence` | Sequence of input events with frame delays | 213 | `get_input_actions` | List all input actions | 214 | `set_input_action` | Create/modify input action | 215 216 ### Runtime Tools (19) 217 | Tool | Description | 218 |------|-------------| 219 | `get_game_scene_tree` | Scene tree of running game | 220 | `get_game_node_properties` | Node properties in running game | 221 | `set_game_node_property` | Set node property in running game | 222 | `execute_game_script` | Run GDScript in game context | 223 | `capture_frames` | Multi-frame screenshot capture | 224 | `monitor_properties` | Record property values over time | 225 | `start_recording` | Start input recording | 226 | `stop_recording` | Stop input recording | 227 | `replay_recording` | Replay recorded input | 228 | `find_nodes_by_script` | Find game nodes by script | 229 | `get_autoload` | Get autoload node properties | 230 | `batch_get_properties` | Batch get multiple node properties | 231 | `find_ui_elements` | Find UI elements in game | 232 | `click_button_by_text` | Click button by text content | 233 | `wait_for_node` | Wait for node to appear | 234 | `find_nearby_nodes` | Find nodes near position | 235 | `navigate_to` | Navigate to target position | 236 | `move_to` | Walk character to target | 237 238 ### Animation Tools (6) 239 | Tool | Description | 240 |------|-------------| 241 | `list_animations` | List all animations in AnimationPlayer | 242 | `create_animation` | Create new animation | 243 | `add_animation_track` | Add track (value/position/rotation/method/bezier) | 244 | `set_animation_keyframe` | Insert keyframe into track | 245 | `get_animation_info` | Detailed animation info with all tracks/keys | 246 | `remove_animation` | Remove an animation | 247 248 ### TileMap Tools (6) 249 | Tool | Description | 250 |------|-------------| 251 | `tilemap_set_cell` | Set a single tile cell | 252 | `tilemap_fill_rect` | Fill rectangular region with tiles | 253 | `tilemap_get_cell` | Get tile data at cell | 254 | `tilemap_clear` | Clear all cells | 255 | `tilemap_get_info` | TileMapLayer info and tile set sources | 256 | `tilemap_get_used_cells` | List of used cells | 257 258 ### Theme & UI Tools (6) 259 | Tool | Description | 260 |------|-------------| 261 | `create_theme` | Create Theme resource file | 262 | `set_theme_color` | Set theme color override | 263 | `set_theme_constant` | Set theme constant override | 264 | `set_theme_font_size` | Set theme font size override | 265 | `set_theme_stylebox` | Set StyleBoxFlat override | 266 | `get_theme_info` | Get theme overrides info | 267 268 ### Profiling Tools (2) 269 | Tool | Description | 270 |------|-------------| 271 | `get_performance_monitors` | All performance monitors (FPS, memory, physics, etc.) | 272 | `get_editor_performance` | Quick performance summary | 273 274 ### Batch & Refactoring Tools (8) 275 | Tool | Description | 276 |------|-------------| 277 | `find_nodes_by_type` | Find all nodes of a type | 278 | `find_signal_connections` | Find all signal connections in scene | 279 | `batch_set_property` | Set property on all nodes of a type | 280 | `find_node_references` | Search project files for pattern | 281 | `get_scene_dependencies` | Get resource dependencies | 282 | `cross_scene_set_property` | Set property across all scenes | 283 | `find_script_references` | Find where script/resource is used | 284 | `detect_circular_dependencies` | Find circular scene dependencies | 285 286 ### Shader Tools (6) 287 | Tool | Description | 288 |------|-------------| 289 | `create_shader` | Create shader with template | 290 | `read_shader` | Read shader file | 291 | `edit_shader` | Edit shader (replace/search-replace) | 292 | `assign_shader_material` | Assign ShaderMaterial to node | 293 | `set_shader_param` | Set shader parameter | 294 | `get_shader_params` | Get all shader parameters | 295 296 ### Export Tools (3) 297 | Tool | Description | 298 |------|-------------| 299 | `list_export_presets` | List export presets | 300 | `export_project` | Get export command for preset | 301 | `get_export_info` | Export-related project info | 302 303 ### Resource Tools (6) 304 | Tool | Description | 305 |------|-------------| 306 | `read_resource` | Read .tres resource properties | 307 | `edit_resource` | Edit resource properties | 308 | `create_resource` | Create new .tres resource | 309 | `get_resource_preview` | Get resource thumbnail | 310 | `add_autoload` | Register autoload singleton | 311 | `remove_autoload` | Remove autoload singleton | 312 313 ### Physics Tools (6) 314 | Tool | Description | 315 |------|-------------| 316 | `setup_physics_body` | Configure physics body properties | 317 | `setup_collision` | Add collision shapes to nodes | 318 | `set_physics_layers` | Set collision layer/mask | 319 | `get_physics_layers` | Get collision layer/mask info | 320 | `get_collision_info` | Get collision shape details | 321 | `add_raycast` | Add RayCast2D/3D node | 322 323 ### 3D Scene Tools (6) 324 | Tool | Description | 325 |------|-------------| 326 | `add_mesh_instance` | Add MeshInstance3D with primitive mesh | 327 | `setup_camera_3d` | Configure Camera3D properties | 328 | `setup_lighting` | Add/configure light nodes | 329 | `setup_environment` | Configure WorldEnvironment | 330 | `add_gridmap` | Set up GridMap node | 331 | `set_material_3d` | Set StandardMaterial3D properties | 332 333 ### Particle Tools (5) 334 | Tool | Description | 335 |------|-------------| 336 | `create_particles` | Create GPUParticles2D/3D | 337 | `set_particle_material` | Configure ParticleProcessMaterial | 338 | `set_particle_color_gradient` | Set color gradient for particles | 339 | `apply_particle_preset` | Apply preset (fire, smoke, sparks, etc.) | 340 | `get_particle_info` | Get particle system details | 341 342 ### Navigation Tools (6) 343 | Tool | Description | 344 |------|-------------| 345 | `setup_navigation_region` | Configure NavigationRegion | 346 | `setup_navigation_agent` | Configure NavigationAgent | 347 | `bake_navigation_mesh` | Bake navigation mesh | 348 | `set_navigation_layers` | Set navigation layers | 349 | `get_navigation_info` | Get navigation setup info | 350 351 ### Audio Tools (6) 352 | Tool | Description | 353 |------|-------------| 354 | `add_audio_player` | Add AudioStreamPlayer node | 355 | `add_audio_bus` | Add audio bus | 356 | `add_audio_bus_effect` | Add effect to audio bus | 357 | `set_audio_bus` | Configure audio bus properties | 358 | `get_audio_bus_layout` | Get audio bus layout info | 359 | `get_audio_info` | Get audio-related node info | 360 361 ### AnimationTree Tools (4) 362 | Tool | Description | 363 |------|-------------| 364 | `create_animation_tree` | Create AnimationTree | 365 | `get_animation_tree_structure` | Get tree structure | 366 | `set_tree_parameter` | Set AnimationTree parameter | 367 | `add_state_machine_state` | Add state to state machine | 368 369 ### State Machine Tools (3) 370 | Tool | Description | 371 |------|-------------| 372 | `remove_state_machine_state` | Remove state from state machine | 373 | `add_state_machine_transition` | Add transition between states | 374 | `remove_state_machine_transition` | Remove state transition | 375 376 ### Blend Tree Tools (1) 377 | Tool | Description | 378 |------|-------------| 379 | `set_blend_tree_node` | Configure blend tree nodes | 380 381 ### Analysis & Search Tools (4) 382 | Tool | Description | 383 |------|-------------| 384 | `analyze_scene_complexity` | Analyze scene performance | 385 | `analyze_signal_flow` | Map signal connections | 386 | `find_unused_resources` | Find unreferenced resources | 387 | `get_project_statistics` | Get project-wide statistics | 388 389 ### Testing & QA Tools (6) 390 | Tool | Description | 391 |------|-------------| 392 | `run_test_scenario` | Run automated test scenario | 393 | `assert_node_state` | Assert node property values | 394 | `assert_screen_text` | Check for text on screen | 395 | `compare_screenshots` | Compare two screenshots | 396 | `run_stress_test` | Run performance stress test | 397 | `get_test_report` | Get test results report | 398 399 ## Key Features 400 401 - **UndoRedo Integration**: All node/property operations support Ctrl+Z 402 - **Smart Type Parsing**: `"Vector2(100, 200)"`, `"#ff0000"`, `"Color(1,0,0)"` auto-converted 403 - **Auto-Reconnect**: Exponential backoff reconnection (1s → 2s → 4s ... → 60s max) 404 - **Heartbeat**: 10s ping/pong keeps connection alive 405 - **Helpful Errors**: Error responses include suggestions for next steps 406 407 ## Competitive Comparison 408 409 ### Tool Count 410 411 | Category | Godot MCP Pro | GDAI MCP ($19) | tomyud1 (free) | Dokujaa (free) | Coding-Solo (free) | ee0pdt (free) | bradypp (free) | 412 |----------|:---:|:---:|:---:|:---:|:---:|:---:|:---:| 413 | Project | 7 | 5 | 4 | 0 | 2 | 2 | 2 | 414 | Scene | 9 | 8 | 11 | 9 | 3 | 4 | 5 | 415 | Node | **14** | 8 | 0 | 8 | 2 | 3 | 0 | 416 | Script | **8** | 5 | 6 | 4 | 0 | 5 | 0 | 417 | Editor | **9** | 5 | 1 | 5 | 1 | 3 | 2 | 418 | Input | **7** | 2 | 0 | 0 | 0 | 0 | 0 | 419 | Runtime | **19** | 0 | 0 | 0 | 0 | 0 | 0 | 420 | Animation | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 421 | TileMap | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 422 | Theme/UI | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 423 | Profiling | **2** | 0 | 0 | 0 | 0 | 0 | 0 | 424 | Batch/Refactor | **8** | 0 | 0 | 0 | 0 | 0 | 0 | 425 | Shader | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 426 | Export | **3** | 0 | 0 | 0 | 0 | 0 | 0 | 427 | Resource | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 428 | Physics | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 429 | 3D Scene | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 430 | Particle | **5** | 0 | 0 | 0 | 0 | 0 | 0 | 431 | Navigation | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 432 | Audio | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 433 | AnimationTree | **4** | 0 | 0 | 0 | 0 | 0 | 0 | 434 | State Machine | **3** | 0 | 0 | 0 | 0 | 0 | 0 | 435 | Blend Tree | **1** | 0 | 0 | 0 | 0 | 0 | 0 | 436 | Analysis | **4** | 0 | 0 | 0 | 0 | 0 | 0 | 437 | Testing/QA | **6** | 0 | 0 | 0 | 0 | 0 | 0 | 438 | Asset/AI | 0 | 0 | 1 | 6 | 0 | 0 | 0 | 439 | Material | 0 | 0 | 0 | 2 | 0 | 0 | 0 | 440 | Other | 0 | 0 | 9 | 5 | 5 | 2 | 1 | 441 | Android Deploy | **3** | 0 | 0 | 0 | 0 | 0 | 0 | 442 | **Total** | **172** | ~30 | **32** | **39** | **13** | **19** | **10** | 443 444 ### Feature Matrix 445 446 | Feature | Godot MCP Pro | GDAI MCP ($19) | tomyud1 (free) | Dokujaa (free) | Coding-Solo (free) | 447 |---------|:---:|:---:|:---:|:---:|:---:| 448 | **Connection** | WebSocket (real-time) | stdio (Python) | WebSocket | TCP Socket | Headless CLI | 449 | **Undo/Redo** | Yes | Yes | No | No | No | 450 | **JSON-RPC 2.0** | Yes | Custom | Custom | Custom | N/A | 451 | **Auto-reconnect** | Yes (exponential backoff) | N/A | No | No | N/A | 452 | **Heartbeat** | Yes (10s ping/pong) | No | No | No | No | 453 | **Error suggestions** | Yes (contextual hints) | No | No | No | No | 454 | **Screenshot capture** | Yes (editor + game) | Yes | No | No | No | 455 | **Game input simulation** | Yes (key/mouse/action/sequence) | Yes (basic) | No | No | No | 456 | **Runtime inspection** | Yes (scene tree + properties + monitor) | No | No | No | No | 457 | **Signal management** | Yes (connect/disconnect/inspect) | No | No | No | No | 458 | **Browser visualizer** | No | No | Yes | No | No | 459 | **AI 3D mesh generation** | No | No | No | Yes (Meshy API) | No | 460 461 ### Exclusive Categories (No Competitor Has These) 462 463 | Category | Tools | Why It Matters | 464 |----------|-------|----------------| 465 | **Animation** | 6 tools | Create animations, add tracks, set keyframes — all programmatically | 466 | **TileMap** | 6 tools | Set cells, fill rects, query tile data — essential for 2D level design | 467 | **Theme/UI** | 6 tools | StyleBox, colors, fonts — build UI themes without manual editor work | 468 | **Profiling** | 2 tools | FPS, memory, draw calls, physics — performance monitoring | 469 | **Batch/Refactor** | 8 tools | Find by type, batch property changes, cross-scene updates, dependency analysis | 470 | **Shader** | 6 tools | Create/edit shaders, assign materials, set parameters | 471 | **Export** | 3 tools | List presets, get export commands, check templates | 472 | **Physics** | 6 tools | Set up collision shapes, bodies, raycasts, and layer management | 473 | **3D Scene** | 6 tools | Add meshes, cameras, lights, environment, GridMap support | 474 | **Particle** | 5 tools | Create particles with custom materials, presets, and gradients | 475 | **Navigation** | 6 tools | Configure navigation regions, agents, pathfinding, baking | 476 | **Audio** | 6 tools | Complete audio bus system, effects, players, live management | 477 | **AnimationTree** | 4 tools | Build state machines with transitions and blend trees | 478 | **State Machine** | 3 tools | Advanced state machine management for complex animations | 479 | **Testing/QA** | 6 tools | Automated testing, assertions, stress testing, screenshot comparison | 480 | **Runtime** | 19 tools | Inspect and control game at runtime: inspect, record, replay, navigate | 481 482 ### Architecture Advantages 483 484 | Aspect | Godot MCP Pro | Typical Competitor | 485 |--------|--------------|-------------------| 486 | **Protocol** | JSON-RPC 2.0 (standard, extensible) | Custom JSON or CLI-based | 487 | **Connection** | Persistent WebSocket with heartbeat | Per-command subprocess or raw TCP | 488 | **Reliability** | Auto-reconnect with exponential backoff (1s→60s) | Manual reconnection required | 489 | **Type Safety** | Smart type parsing (Vector2, Color, Rect2, hex colors) | String-only or limited types | 490 | **Error Handling** | Structured errors with codes + suggestions | Generic error messages | 491 | **Undo Support** | All mutations go through UndoRedo system | Direct modifications (no undo) | 492 | **Port Management** | Auto-scan ports 6505-6509 | Fixed port, conflicts possible | 493 494 ## License 495 496 Proprietary — see [LICENSE](LICENSE) for details. Purchase includes lifetime updates.