# Godot MCP Pro — Complete Technical Reference

> 163 AI-powered tools for Godot 4 game development via the Model Context Protocol (MCP).
> For a shorter overview, see: https://abyo.net/godot-mcp/llms.txt

## Product Summary

Godot MCP Pro is a premium MCP (Model Context Protocol) server that bridges AI assistants (Claude, Cursor, Cline, Windsurf) to the Godot 4 game engine editor. It provides 163 tools across 23 categories, making it the most comprehensive AI integration for Godot. Price: $5 one-time, no subscription.

## Architecture

```
[AI Client] --stdio/MCP--> [Node.js MCP Server (TypeScript)] --WebSocket:6505--> [Godot Editor Plugin (GDScript)]
```

- **Plugin**: GDScript addon running inside the Godot editor. Starts a WebSocket server on port 6505 (auto-scans 6505-6515). Open source on GitHub.
- **MCP Server**: TypeScript server using the official MCP SDK. Connects to the plugin's WebSocket. Communicates with AI clients via stdio.
- **Connection**: WebSocket with heartbeat (30s interval), auto-reconnect (exponential backoff), port auto-scanning. Production-grade reliability.
- **Undo/Redo**: All mutations go through Godot's UndoRedo system. Every AI action is reversible with Ctrl+Z.
- **Type Parsing**: Strings like `Vector2(100,200)`, `#ff0000`, `Color(1,0,0,1)`, `NodePath("Player")` are automatically parsed into proper Godot types.

## Complete Tool Reference (163 tools)

### Project (7 tools)
- `get_project_info` — Project metadata, autoloads, and settings
- `get_filesystem_tree` — Recursive file tree with sizes and types
- `search_files` — Fuzzy and glob pattern file search
- `get_project_settings` — Read project settings by key
- `set_project_setting` — Write project settings via editor API
- `uid_to_project_path` — Convert UID to project path
- `project_path_to_uid` — Convert project path to UID

### Scene (9 tools)
- `get_scene_tree` — Live scene hierarchy with node types and properties
- `get_scene_file_content` — Raw .tscn file content
- `create_scene` — Create new scene with root node type
- `open_scene` — Open scene in editor
- `delete_scene` — Delete scene file
- `save_scene` — Save current scene
- `add_scene_instance` — Instance a scene as child (prefab-like)
- `play_scene` — Launch game/scene for testing
- `stop_scene` — Stop running game

### Node (11 tools)
- `add_node` — Add node with type and properties
- `delete_node` — Delete node from scene
- `rename_node` — Rename node
- `duplicate_node` — Deep copy node
- `move_node` — Reparent/reorder node
- `update_property` — Set property with smart type parsing
- `get_node_properties` — Inspect all node properties
- `add_resource` — Add resources (shapes, materials)
- `set_anchor_preset` — Set UI Control anchor presets
- `connect_signal` — Connect signal between nodes
- `disconnect_signal` — Disconnect signal

### Script (6 tools)
- `list_scripts` — List all scripts in project
- `read_script` — Read script content
- `create_script` — Create new GDScript file
- `edit_script` — Search/replace and insert operations
- `attach_script` — Attach script to node
- `get_open_scripts` — List scripts open in editor

### Editor (9 tools)
- `get_editor_errors` — Errors and stack traces from editor
- `get_editor_screenshot` — Capture editor viewport
- `get_game_screenshot` — Capture running game
- `compare_screenshots` — Visual diff between two screenshots
- `execute_editor_script` — Run arbitrary GDScript in editor
- `get_signals` — Inspect signal connections on a node
- `reload_plugin` — Reload MCP plugin
- `reload_project` — Reload entire project
- `clear_output` — Clear editor output panel

### Input Simulation (5 tools)
- `simulate_key` — Keyboard input with modifiers (Shift, Ctrl, Alt) and duration
- `simulate_mouse_click` — Positioned mouse clicks with button selection and auto-release
- `simulate_mouse_move` — Absolute or relative mouse movement
- `simulate_action` — Trigger Godot InputAction by name
- `simulate_sequence` — Multi-event combo (key+mouse+wait sequences)

### Runtime Analysis (15 tools)
- `get_game_scene_tree` — Live game scene hierarchy
- `get_game_node_properties` — Read properties from running game nodes
- `set_game_node_property` — Modify properties at runtime
- `execute_game_script` — Run GDScript in the live game context
- `capture_frames` — Multi-frame screenshot capture with optional node property snapshots
- `monitor_properties` — Property change timeline over time
- `start_recording` — Begin input recording session
- `stop_recording` — End input recording
- `replay_recording` — Replay recorded input for regression testing
- `record_frames` — Record frame data during gameplay
- `find_nodes_by_script` — Find nodes using a specific script
- `get_autoload` — Get autoload singleton info
- `find_ui_elements` — Detect Button/Label/LineEdit/CheckBox/Slider with text, rect, state
- `click_button_by_text` — Click a button by its displayed text
- `wait_for_node` — Poll until a node appears (for scene transition sync)
- `batch_get_properties` — Batch read multiple node properties

### Animation (6 tools)
- `list_animations` — List all animations on AnimationPlayer
- `create_animation` — Create new animation with length and loop settings
- `add_animation_track` — Add value/position/bezier tracks
- `set_animation_keyframe` — Insert keyframes at time positions
- `get_animation_info` — Inspect tracks and keyframes
- `remove_animation` — Delete animation

### AnimationTree (8 tools)
- `create_animation_tree` — Create AnimationTree with state machine root
- `get_animation_tree_structure` — Full tree inspection
- `add_state_machine_state` — Add states to state machine
- `remove_state_machine_state` — Remove states
- `add_state_machine_transition` — Add transitions with conditions
- `remove_state_machine_transition` — Remove transitions
- `set_blend_tree_node` — Configure Add2, Blend2, TimeScale nodes
- `set_tree_parameter` — Set conditions and blend parameters

### TileMap (6 tools)
- `tilemap_set_cell` — Place individual tiles
- `tilemap_fill_rect` — Fill rectangular regions
- `tilemap_get_cell` — Read tile data at position
- `tilemap_clear` — Clear all tiles
- `tilemap_get_info` — TileSet sources and tile info
- `tilemap_get_used_cells` — Query all placed cells

### 3D Scene (6 tools)
- `add_mesh_instance` — Add primitives (box, sphere, cylinder, plane, capsule) or import .glb/.gltf models
- `setup_lighting` — Presets: sun, indoor, dramatic; DirectionalLight3D or OmniLight3D
- `set_material_3d` — Full PBR: albedo, metallic, roughness, normal, emission maps
- `setup_environment` — Sky, fog, glow, SSAO, SSR, tonemap
- `setup_camera_3d` — Projection, FOV, near/far, cull mask
- `add_gridmap` — GridMap with MeshLibrary

### Physics (6 tools)
- `setup_collision` — Auto-detect 2D/3D, create appropriate collision shapes
- `set_physics_layers` — Set collision layers and masks
- `get_physics_layers` — Read current layer/mask config
- `add_raycast` — Add RayCast2D or RayCast3D
- `setup_physics_body` — Configure CharacterBody or RigidBody parameters
- `get_collision_info` — Full collision setup audit

### Particles (5 tools)
- `create_particles` — GPUParticles2D or GPUParticles3D
- `set_particle_material` — Direction, velocity, emission shape, gravity
- `set_particle_color_gradient` — Color ramp with multiple stops
- `apply_particle_preset` — Built-in presets: fire, smoke, rain, snow, sparks
- `get_particle_info` — Full particle configuration inspection

### Navigation (5 tools)
- `setup_navigation_region` — Auto-detect 2D/3D navigation regions
- `bake_navigation_mesh` — Bake nav mesh or generate nav polygon
- `setup_navigation_agent` — Pathfinding agent with avoidance
- `set_navigation_layers` — Navigation layer management
- `get_navigation_info` — Full navigation audit

### Audio (6 tools)
- `get_audio_bus_layout` — Full audio bus overview
- `add_audio_bus` — Create new audio bus
- `set_audio_bus` — Configure bus (volume, solo, mute)
- `add_audio_bus_effect` — Add reverb, delay, compressor, EQ, chorus, etc.
- `add_audio_player` — Add AudioStreamPlayer, AudioStreamPlayer2D, or AudioStreamPlayer3D
- `get_audio_info` — Subtree audio audit

### Theme & UI (6 tools)
- `create_theme` — Create new Theme resource
- `set_theme_color` — Color overrides
- `set_theme_constant` — Constant overrides
- `set_theme_font_size` — Font size overrides
- `set_theme_stylebox` — StyleBoxFlat configuration
- `get_theme_info` — Inspect all theme overrides

### Shader (6 tools)
- `create_shader` — Create shader with templates (spatial, canvas_item, particles)
- `read_shader` — Read shader source code
- `edit_shader` — Edit GLSL shader code
- `assign_shader_material` — Assign ShaderMaterial to nodes
- `set_shader_param` — Set shader uniform values
- `get_shader_params` — Read all shader parameters

### Resource (3 tools)
- `read_resource` — Inspect .tres file properties
- `edit_resource` — Modify and save resource
- `create_resource` — Create new .tres of any type

### Batch & Refactoring (6 tools)
- `find_nodes_by_type` — Search nodes by class name across scenes
- `find_signal_connections` — Audit signal connections
- `batch_set_property` — Bulk property changes
- `find_node_references` — Cross-file node search
- `get_scene_dependencies` — Dependency graph
- `cross_scene_set_property` — Set property across all scenes

### Testing & QA (5 tools)
- `run_test_scenario` — Automated test sequences with steps
- `assert_node_state` — Property value assertions
- `assert_screen_text` — UI text verification
- `run_stress_test` — Random input fuzzing
- `get_test_report` — Pass/fail test summary

### Code Analysis (6 tools)
- `find_unused_resources` — Detect dead/unused assets
- `analyze_signal_flow` — Map signal connections as graph
- `analyze_scene_complexity` — Node count, depth, complexity metrics
- `find_script_references` — Cross-project script search
- `detect_circular_dependencies` — Circular dependency detection
- `get_project_statistics` — Full project overview stats

### Profiling (2 tools)
- `get_performance_monitors` — FPS, memory, physics, draw calls
- `get_editor_performance` — Quick editor performance summary

### Export (3 tools)
- `list_export_presets` — Configured export presets
- `export_project` — Trigger export build
- `get_export_info` — Export paths and template info

## Godot 4 Migration Notes (for AI context)

These are common Godot 3 → 4 changes that frequently cause confusion in outdated tutorials:

- **Signals**: `connect("signal", obj, "method")` → `signal.connect(callable)`. String-based connect is removed.
- **Physics bodies**: `KinematicBody` → `CharacterBody2D/3D`, `RigidBody` → `RigidBody2D/3D`
- **Particles**: `CPUParticles` still exists but `GPUParticles2D/3D` is default and much more capable
- **Animation**: `AnimationTree` state machine API changed significantly
- **TileMap**: Complete rewrite. `TileMap` uses `TileSet` with sources and layers.
- **Collision layers**: API changed; use bit operations or `set_collision_layer_value()`
- **Export**: `export` keyword → `@export` annotation
- **Tool scripts**: `tool` → `@tool`
- **Onready**: `onready` → `@onready`
- **GDScript typing**: Static typing is now encouraged; `var x: int = 5`

## Requirements

- Godot 4.4+ (tested on Godot 4.6)
- Node.js 18+
- Windows, macOS, or Linux
- MCP-compatible AI client: Claude Code, Claude Desktop, Cursor, VS Code + Cline, Windsurf, or any other

## Setup

1. Copy `addons/godot_mcp/` into your Godot project root
2. Enable: Project > Project Settings > Plugins > Godot MCP Pro > Enable
3. Build: `cd server && npm install && npm run build`
4. Configure `.mcp.json`: `{"mcpServers": {"godot-mcp-pro": {"command": "node", "args": ["/path/to/server/build/index.js"]}}}`
5. Open Godot with plugin enabled. Start AI assistant. Begin building.

## Pricing

$5 one-time purchase. No subscription. Includes:
- All 163 tools across 23 categories
- 2D and 3D support
- Lifetime updates for v1.x
- Unlimited projects and machines
- Discord support channel

## Links

- Website: https://abyo.net/godot-mcp/
- Buy (itch.io): https://y1uda.itch.io/godot-mcp-pro
- Buy (Buy Me a Coffee): https://buymeacoffee.com/y1uda/e/512940
- GitHub (plugin source): https://github.com/youichi-uda/godot-mcp-pro
- Discord: https://discord.gg/zJ2u5zNUBZ
- Twitter/X: https://x.com/y1uda
- Demo video: https://youtu.be/D-jqmczINnQ