GDotMCP

<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

cd godot-mcp-server
npm install
npm run build

3. Configure Your MCP Client

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

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

Cursor — Edit .cursor/mcp.json:

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

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

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

Claude Code (CLI):

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:

# 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:

   # 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:

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:

# 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

# 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 by youichi-uda. GDotMCP is an open-source implementation built on similar architectural principles.

License

MIT