<p align="center">
  <img src="img/banner.png" alt="GDotMCP" width="100%">
</p>

<h1 align="center">GDotMCP</h1>

<p align="center">
  <strong>174 MCP tools for AI-powered Godot 4 development.</strong><br>
  Scene manipulation, scripting, animation, 3D, physics, particles, audio, shaders, runtime analysis, navigation, testing & more.
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#all-174-tools">Tools</a> •
  <a href="#features">Features</a> •
  <a href="#troubleshooting">Troubleshooting</a>
</p>

---

## Architecture

```
AI Assistant ←—stdio/MCP—→ Node.js Server ←—WebSocket:6505-6514—→ Godot Editor Plugin
```

- **Real-time**: WebSocket connection means instant feedback, no file polling
- **Editor Integration**: Full access to Godot's editor API, UndoRedo system, and scene tree
- **JSON-RPC 2.0**: Standard protocol with proper error codes and suggestions
- **Runtime Inspection**: Live game scene tree, property monitoring, input recording/replay

---

## Quick Start

### 1. Install the Godot Plugin

Copy `addons/gdotmcp/` into your Godot project's `addons/` directory.

Enable the plugin: **Project → Project Settings → Plugins → GDotMCP → Enable**

The plugin will auto-inject 3 autoloads for runtime game inspection:
- `MCPScreenshot` — captures game viewport
- `MCPInputService` — injects input events into the running game
- `MCPGameInspector` — runtime scene tree, properties, recording

### 2. Build the MCP Server

```bash
cd godot-mcp-server
npm install
npm run build
```

### 3. Configure Your MCP Client

**Claude Desktop** — Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gdotmcp": {
      "command": "node",
      "args": ["D:\\GDotMCP\\godot-mcp-server\\dist\\index.js"]
    }
  }
}
```

**Cursor** — Edit `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gdotmcp": {
      "command": "node",
      "args": ["D:\\GDotMCP\\godot-mcp-server\\dist\\index.js"]
    }
  }
}
```

**OpenCode** — Edit `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "gdotmcp": {
      "type": "local",
      "command": ["node", "D:\\GDotMCP\\godot-mcp-server\\dist\\index.js"],
      "enabled": true
    }
  }
}
```

**Claude Code (CLI)**:

```bash
claude mcp add gdotmcp -- node D:\GDotMCP\godot-mcp-server\dist\index.js
```

### 4. Use It

1. **Open Godot** with the GDotMCP plugin enabled
2. **Start your MCP client** (Claude Desktop, Cursor, OpenCode, etc.)
3. The MCP server connects to Godot automatically on ports 6505-6514

### 5. Install the AI Skill (Optional)

GDotMCP includes a skill file that gives AI assistants detailed guidance on how to use all 174 tools effectively. Install it for better AI assistance:

**Claude Code:**
```bash
# Copy skill to your project
cp -r skills/gdotmcp ~/.claude/skills/
```

**Other AI Clients:**
Copy `skills/gdotmcp/SKILL.md` to your AI client's skill/context directory.

The skill covers:
- Essential workflows (2D/3D scene building, scripting, playtesting)
- Property value formats and GDScript gotchas
- Advanced patterns (shaders, navigation, AnimationTree)
- Runtime debugging and testing
- Troubleshooting common issues

---

## All 174 Tools

### Project Tools (10)

| Tool | Description |
|------|-------------|
| `get_project_info` | Project metadata, version, viewport, autoloads |
| `get_filesystem_tree` | Recursive file tree with filtering |
| `search_files` | Fuzzy/glob file search |
| `search_in_files` | Search content in project files |
| `get_project_settings` | Read project.godot settings |
| `set_project_setting` | Set project settings via editor API |
| `uid_to_project_path` | UID → res:// conversion |
| `project_path_to_uid` | res:// → UID conversion |
| `add_autoload` | Register autoload singleton |
| `remove_autoload` | Remove autoload singleton |

### Scene Tools (10)

| Tool | Description |
|------|-------------|
| `get_scene_tree` | Live scene tree with hierarchy |
| `get_scene_file_content` | Raw .tscn file content |
| `create_scene` | Create new scene files |
| `open_scene` | Open scene in editor |
| `delete_scene` | Delete scene file |
| `add_scene_instance` | Instance scene as child node |
| `play_scene` | Run scene (main/current/custom) |
| `stop_scene` | Stop running scene |
| `save_scene` | Save current scene to disk |
| `get_scene_exports` | Get @export variables from scene |

### Node Tools (17)

| Tool | Description |
|------|-------------|
| `add_node` | Add node with type and properties |
| `delete_node` | Delete node (with undo support) |
| `duplicate_node` | Duplicate node and children |
| `move_node` | Move/reparent node |
| `update_property` | Set any property (auto type parsing) |
| `get_node_properties` | Get all node properties |
| `add_resource` | Add Shape/Material/etc to node |
| `set_anchor_preset` | Set Control anchor preset |
| `rename_node` | Rename a node in the scene |
| `connect_signal` | Connect signal between nodes |
| `disconnect_signal` | Disconnect signal connection |
| `get_node_groups` | Get groups a node belongs to |
| `set_node_groups` | Set node group membership |
| `find_nodes_in_group` | Find all nodes in a group |
| `get_editor_selection` | Get currently selected scene nodes |
| `select_nodes` | Select, focus, and inspect scene nodes |
| `clear_editor_selection` | Clear the editor scene selection |

### Script Tools (7)

| Tool | Description |
|------|-------------|
| `list_scripts` | List all scripts with class info |
| `read_script` | Read script content |
| `create_script` | Create new script with template |
| `edit_script` | Search/replace or full edit |
| `attach_script` | Attach script to node |
| `get_open_scripts` | List scripts open in editor |
| `validate_script` | Validate GDScript syntax |

### Editor Tools (13)

| Tool | Description |
|------|-------------|
| `get_editor_errors` | Get errors and warnings |
| `get_output_log` | Read output panel content |
| `get_editor_screenshot` | Capture editor viewport |
| `get_game_screenshot` | Capture running game viewport |
| `execute_editor_script` | Run arbitrary GDScript in editor |
| `clear_output` | Clear output panel |
| `reload_plugin` | Reload the MCP plugin |
| `reload_project` | Rescan filesystem and reload scripts |
| `get_signals` | Get all signals of a node with connections |
| `compare_screenshots` | Diff two images pixel-by-pixel |
| `set_auto_dismiss` | Toggle dialog auto-dismiss |
| `get_editor_camera` | Get 3D editor camera transform |
| `set_editor_camera` | Set 3D editor camera position/rotation |

### Input Tools (5)

| Tool | Description |
|------|-------------|
| `simulate_key` | Simulate keyboard key press/release |
| `simulate_mouse_click` | Simulate mouse click at position |
| `simulate_mouse_move` | Simulate mouse movement |
| `simulate_action` | Simulate Godot Input Action |
| `simulate_sequence` | Sequence of input events with frame delays |

### Runtime Tools (19)

| Tool | Description |
|------|-------------|
| `get_game_scene_tree` | Scene tree of running game |
| `get_game_node_properties` | Node properties in running game |
| `set_game_node_property` | Set node property in running game |
| `execute_game_script` | Run GDScript in game context |
| `capture_frames` | Multi-frame screenshot capture |
| `monitor_properties` | Record property values over time |
| `start_recording` | Start input recording |
| `stop_recording` | Stop input recording |
| `replay_recording` | Replay recorded input |
| `find_nodes_by_script` | Find game nodes by script |
| `get_autoload` | Get autoload node properties |
| `batch_get_properties` | Batch get multiple node properties |
| `find_ui_elements` | Find UI elements in game |
| `click_button_by_text` | Click button by text content |
| `wait_for_node` | Wait for node to appear |
| `find_nearby_nodes` | Find nodes near position |
| `navigate_to` | Navigate to target position |
| `move_to` | Walk character to target |
| `watch_signals` | Monitor signal emissions |

### Animation Tools (6)

| Tool | Description |
|------|-------------|
| `list_animations` | List all animations in AnimationPlayer |
| `create_animation` | Create new animation |
| `add_animation_track` | Add track (value/position/rotation/method/bezier) |
| `set_animation_keyframe` | Insert keyframe into track |
| `get_animation_info` | Detailed animation info with all tracks/keys |
| `remove_animation` | Remove an animation |

### AnimationTree Tools (8)

| Tool | Description |
|------|-------------|
| `create_animation_tree` | Create AnimationTree |
| `get_animation_tree_structure` | Get tree structure |
| `add_state_machine_state` | Add state to state machine |
| `remove_state_machine_state` | Remove state from state machine |
| `add_state_machine_transition` | Add transition between states |
| `remove_state_machine_transition` | Remove state transition |
| `set_blend_tree_node` | Configure blend tree nodes |
| `set_tree_parameter` | Set AnimationTree parameter |

### TileMap Tools (6)

| Tool | Description |
|------|-------------|
| `tilemap_set_cell` | Set a single tile cell |
| `tilemap_fill_rect` | Fill rectangular region with tiles |
| `tilemap_get_cell` | Get tile data at cell |
| `tilemap_clear` | Clear all cells |
| `tilemap_get_info` | TileMapLayer info and tile set sources |
| `tilemap_get_used_cells` | List of used cells |

### Theme Tools (7)

| Tool | Description |
|------|-------------|
| `create_theme` | Create Theme resource file |
| `set_theme_color` | Set theme color override |
| `set_theme_constant` | Set theme constant override |
| `set_theme_font_size` | Set theme font size override |
| `set_theme_stylebox` | Set StyleBoxFlat override |
| `setup_control` | Configure Control layout (anchors, size flags) |
| `get_theme_info` | Get theme overrides info |

### Shader Tools (6)

| Tool | Description |
|------|-------------|
| `create_shader` | Create shader with template |
| `read_shader` | Read shader file |
| `edit_shader` | Edit shader (replace/search-replace) |
| `assign_shader_material` | Assign ShaderMaterial to node |
| `set_shader_param` | Set shader parameter |
| `get_shader_params` | Get all shader parameters |

### Resource Tools (4)

| Tool | Description |
|------|-------------|
| `read_resource` | Read .tres resource properties |
| `edit_resource` | Edit resource properties |
| `create_resource` | Create new .tres resource |
| `get_resource_preview` | Get resource thumbnail |

### Batch & Refactoring Tools (7)

| Tool | Description |
|------|-------------|
| `find_nodes_by_type` | Find all nodes of a type |
| `find_signal_connections` | Find all signal connections in scene |
| `batch_set_property` | Set property on all nodes of a type |
| `batch_add_nodes` | Add multiple nodes at once |
| `find_node_references` | Search project files for pattern |
| `get_scene_dependencies` | Get resource dependencies |
| `cross_scene_set_property` | Set property across all scenes |

### Physics Tools (6)

| Tool | Description |
|------|-------------|
| `setup_collision` | Add collision shapes to nodes |
| `set_physics_layers` | Set collision layer/mask |
| `get_physics_layers` | Get collision layer/mask info |
| `add_raycast` | Add RayCast2D/3D node |
| `setup_physics_body` | Configure physics body properties |
| `get_collision_info` | Get collision shape details |

### 3D Scene Tools (6)

| Tool | Description |
|------|-------------|
| `add_mesh_instance` | Add MeshInstance3D with primitive mesh |
| `setup_camera_3d` | Configure Camera3D properties |
| `setup_lighting` | Add/configure light nodes |
| `setup_environment` | Configure WorldEnvironment |
| `add_gridmap` | Set up GridMap node |
| `set_material_3d` | Set StandardMaterial3D properties |

### Audio Tools (6)

| Tool | Description |
|------|-------------|
| `add_audio_player` | Add AudioStreamPlayer node |
| `add_audio_bus` | Add audio bus |
| `add_audio_bus_effect` | Add effect to audio bus |
| `set_audio_bus` | Configure audio bus properties |
| `get_audio_bus_layout` | Get audio bus layout info |
| `get_audio_info` | Get audio-related node info |

### Navigation Tools (5)

| Tool | Description |
|------|-------------|
| `setup_navigation_region` | Configure NavigationRegion |
| `setup_navigation_agent` | Configure NavigationAgent |
| `bake_navigation_mesh` | Bake navigation mesh |
| `set_navigation_layers` | Set navigation layers |
| `get_navigation_info` | Get navigation setup info |

### Particle Tools (5)

| Tool | Description |
|------|-------------|
| `create_particles` | Create GPUParticles2D/3D |
| `set_particle_material` | Configure ParticleProcessMaterial |
| `set_particle_color_gradient` | Set color gradient for particles |
| `apply_particle_preset` | Apply preset (fire, smoke, sparks, etc.) |
| `get_particle_info` | Get particle system details |

### Input Map Tools (2)

| Tool | Description |
|------|-------------|
| `get_input_actions` | List all input actions |
| `set_input_action` | Create/modify input action |

### Analysis Tools (6)

| Tool | Description |
|------|-------------|
| `find_unused_resources` | Find unreferenced resources |
| `analyze_signal_flow` | Map signal connections |
| `analyze_scene_complexity` | Analyze scene performance |
| `find_script_references` | Find where script/resource is used |
| `detect_circular_dependencies` | Find circular scene dependencies |
| `get_project_statistics` | Get project-wide statistics |

### Profiling Tools (2)

| Tool | Description |
|------|-------------|
| `get_performance_monitors` | All performance monitors (FPS, memory, physics, etc.) |
| `get_editor_performance` | Quick performance summary |

### Export Tools (3)

| Tool | Description |
|------|-------------|
| `list_export_presets` | List export presets |
| `export_project` | Get export command for preset |
| `get_export_info` | Export-related project info |

### Test Tools (5)

| Tool | Description |
|------|-------------|
| `run_test_scenario` | Run automated test scenario |
| `assert_node_state` | Assert node property values |
| `assert_screen_text` | Check for text on screen |
| `run_stress_test` | Run performance stress test |
| `get_test_report` | Get test results report |

### Android Tools (3)

| Tool | Description |
|------|-------------|
| `list_android_devices` | List ADB connected devices |
| `get_android_preset_info` | Get Android export preset info |
| `deploy_to_android` | Export and deploy APK to device |

---

## Features

- **UndoRedo Integration**: All node/property operations support Ctrl+Z
- **Smart Type Parsing**: `"Vector2(100, 200)"`, `"#ff0000"`, `"Color(1,0,0)"` auto-converted
- **Auto-Reconnect**: Exponential backoff reconnection (1s → 2s → 4s ... → 60s max)
- **Heartbeat**: 5s ping/pong keeps connection alive
- **Helpful Errors**: Error responses include suggestions for next steps
- **Runtime Inspection**: Live game scene tree, property monitoring, input recording/replay
- **174 Tools**: Comprehensive coverage of Godot's API

---

## Troubleshooting

### "No connection available to Godot editor"

The MCP server can't reach Godot. Check:

1. **Godot is running** with the GDotMCP plugin enabled
2. **No stale processes** — Kill all `node` processes and restart your MCP client:
   ```powershell
   # Windows
   Get-Process -Name "node" | Stop-Process -Force
   
   # Linux/macOS
   pkill -f node
   ```
3. **Ports not blocked** — The server uses ports 6505-6514. Ensure no firewall is blocking them.

### "Command timed out after 30000ms"

The Godot editor didn't respond in time. This can happen if:

- The game is paused or blocked by a debugger breakpoint
- A heavy operation is running in the editor
- The WebSocket connection dropped (check Godot output panel for reconnection messages)

### Runtime tools return empty `{}`

The game autoloads aren't responding. This usually means:

1. The game scene isn't playing — use `play_scene` first
2. The MCP autoloads weren't injected — restart Godot with the plugin enabled
3. An async handler issue — ensure you're running the latest build

### Dictionary parameters fail with "got type: 4"

The MCP protocol sends nested objects as JSON strings. The server now handles this automatically with `JSON.parse()` fallback. If you see this error, rebuild the server:

```bash
cd godot-mcp-server
npm run build
```

### Plugin not loading

1. Check **Project → Project Settings → Plugins** for GDotMCP
2. Look at the Godot output panel for error messages
3. Ensure the `addons/gdotmcp/` folder contains all required files

### Multiple MCP server instances

If you see connection issues, ensure only one MCP server instance is running:

```powershell
# Check for multiple node processes
Get-Process -Name "node" | Select-Object Id, StartTime

# Kill all and restart your MCP client
Get-Process -Name "node" | Stop-Process -Force
```

---

## Development

```bash
# TypeScript MCP server
npm run dev          # Watch mode
npm run build        # Build
npm test             # Run tests
npm run typecheck    # Type check
npm run lint         # Lint
```

## Requirements

- Node.js >= 18
- Godot 4.x (tested with 4.7-stable)

## Credits

Inspired by [Godot MCP Pro](https://github.com/youichi-uda/godot-mcp-pro) by [youichi-uda](https://github.com/youichi-uda). GDotMCP is an open-source implementation built on similar architectural principles.

## License

MIT