How do I use GDotMCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@GDotMCP Add a CharacterBody2D player to the current scene" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

GDotMCP

by DohmBoy64Bit

Overview Schema Source Related Servers Discussions Admin

Local

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

Related MCP server: Gear

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

Open Godot with the GDotMCP plugin enabled
Start your MCP client (Claude Desktop, Cursor, OpenCode, etc.)
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

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:

Godot is running with the GDotMCP plugin enabled

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

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:

The game scene isn't playing — use play_scene first
The MCP autoloads weren't injected — restart Godot with the plugin enabled
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

Check Project → Project Settings → Plugins for GDotMCP
Look at the Godot output panel for error messages
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

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

MCP Aggregation Gateway — 22k+ MCP search & call A
cn.pianam.mcp
One AI endpoint to search and call 22k+ MCP servers; 50+ hosted tools work instantly, no key.
Agent Orchestration Search
31
mcp-grokOAuth
io.github.AceDataCloud
MCP server for Grok Imagine AI video generation
AI & Machine Learning Image & Video Processing
31
Danushkumar-V-mcp-discordOAuth
ai.smithery
An MCP server that integrates with Discord to provide AI-powered features.
Communication Social Media App Automation
2
Gessa: game asset generation for AI agentsOAuth
ai.gessa
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
AI & Machine Learning Image & Video Processing Audio Processing
1

Related MCP Servers

GodotIQ
Developer Tools Code Analysis Autonomous Agents
salvo10f
A
license
Not graded
quality
B
maintenance
Intelligent MCP server for AI-assisted Godot 4 development with spatial intelligence, code analysis, and 35 tools
Updated a month ago (2026-08-03 17:22 UTC)
54
MIT
Gear
Developer Tools Code Execution App Automation
wvfp
A
license
A
quality
D
maintenance
An MCP server that enables AI assistants to directly run, inspect, modify, and debug Godot game development projects through 110+ tools covering scenes, scripts, resources, runtime debugging, and asset management.
Updated 3 months ago (2026-06-15 13:26 UTC)
33
21
2
MIT
Godot MCP Server Ultimate
Developer Tools Code Analysis Coding Agents
Dex865378
A
license
B
quality
D
maintenance
Advanced MCP server for Godot 4.6+ with 63 professional tools, enabling AI-assisted game development with backup/rollback, deep script validation, and project health diagnostics.
Updated 5 months ago (2026-04-04 18:49 UTC)
63
159
5
MIT
Godot MCP - Full Control
Games & Gamification Developer Tools Code Execution
tugcantopaloglu
A
license
C
quality
A
maintenance
An MCP server providing AI assistants with 149 tools to fully control the Godot game engine, including runtime code execution, scene manipulation, physics, audio, networking, animation, and more.
Updated 2 months ago (2026-07-13 08:04 UTC)
100
75
449
MIT