Godot Mcp

Godot MCP - Full Control

[](https://modelcontextprotocol.io/introduction) [](https://godotengine.org) [](https://www.typescriptlang.org/) [](https://opensource.org/licenses/MIT)

A comprehensive Model Context Protocol (MCP) server that gives AI assistants full control over the Godot game engine. 149 tools spanning networking, 3D/2D rendering, UI controls, audio effects, animation trees, file I/O, runtime code execution, property inspection, scene manipulation, signal management, physics, project creation, and more.

Acknowledgments

This project is built upon and extends godot-mcp by Solomon Elias (Coding-Solo). The original project provided the foundational architecture including the TypeScript MCP server, headless GDScript operations system, and TCP-based runtime interaction server. Thank you for making this possible with your excellent open-source work!

What's New (Improvements Over Original)

The original godot-mcp provided 20 tools for basic project management and scene creation. This fork extends it to 149 tools with the following major additions:

Runtime Code Execution

• game_eval - Execute arbitrary GDScript code in the running game with return values
• Full await support for async GDScript code
• Works even when the game is paused (PROCESS_MODE_ALWAYS)

Runtime Node Inspection & Manipulation

• game_get_property / game_set_property - Read/write any property on any node by path
• game_call_method - Call any method on any node with arguments
• game_get_node_info - Full node introspection: properties, signals, methods, children
• game_instantiate_scene - Dynamically add scenes to the running game
• game_remove_node - Remove nodes at runtime
• game_change_scene - Switch scenes at runtime
• game_reparent_node - Move nodes between parents

Signal System

• game_connect_signal - Wire up signal connections at runtime
• game_disconnect_signal - Remove signal connections
• game_emit_signal - Emit signals with arguments

Animation & Tweening

• game_play_animation - Control AnimationPlayer (play, stop, pause, list)
• game_tween_property - Smooth property animation with configurable easing

Game Control & Debugging

• game_pause - Pause/unpause the game
• game_performance - FPS, frame time, memory, object counts, draw calls
• game_wait - Wait N frames (timing-sensitive operations)
• game_get_nodes_in_group - Query nodes by group
• game_find_nodes_by_class - Find all nodes of a specific class

Headless Scene Operations (No Running Game Needed)

• read_scene - Parse any .tscn file and get full node tree with properties as JSON
• modify_scene_node - Change node properties in scene files
• remove_scene_node - Remove nodes from scene files
• attach_script - Attach GDScript files to nodes in scenes
• create_resource - Create .tres resource files (materials, themes, etc.)

Project Management

• read_project_settings - Parse project.godot as structured JSON
• modify_project_settings - Change project settings programmatically
• list_project_files - List and filter project files by extension

File I/O

• read_file / write_file / delete_file - Full file system access within Godot projects
• create_directory - Create directory structures for scripts, scenes, assets

Error & Log Capture

• game_get_errors - Get new pusherror/pushwarning messages since last call
• game_get_logs - Get new print output from the running game since last call

Enhanced Input

• game_key_hold / game_key_release - Hold keys down for movement testing (WASD etc.)
• game_scroll - Mouse scroll wheel events
• game_mouse_drag - Drag between two points over multiple frames
• game_gamepad - Gamepad button and axis input events

Project Creation & Configuration

• create_project - Create a new Godot project from scratch
• manage_autoloads - Add, remove, or list autoloads
• manage_input_map - Add, remove, or list input actions and key bindings
• manage_export_presets - Create or modify export preset configuration

Camera, Physics & Audio

• game_get_camera / game_set_camera - Query and control 2D/3D cameras
• game_raycast - Cast physics rays (auto-detects 2D vs 3D)
• game_get_audio - Get audio bus layout and playing streams
• game_spawn_node - Create any node type at runtime with properties
• game_set_shader_param - Set shader parameters on materials
• game_audio_play / game_audio_bus - Full audio playback and bus control
• game_navigate_path - Query navigation paths (2D/3D)
• game_tilemap - Get/set TileMapLayer cells
• game_add_collision - Add collision shapes to physics bodies
• game_environment - Configure post-processing (fog, glow, SSAO, tonemap, etc.)
• game_manage_group - Add/remove nodes from groups
• game_create_timer - Create timer nodes programmatically
• game_set_particles - Configure GPUParticles2D/3D properties and process materials
• game_create_animation - Create animations with value/method/bezier/audio tracks and keyframes
• export_project - Trigger headless project export builds (CI/CD ready)
• game_serialize_state - Save/load entire node tree state as JSON
• game_physics_body - Configure mass, velocity, damping, friction, bounce
• game_create_joint - Create physics joints (pin, spring, hinge, cone, slider)
• game_bone_pose - Get/set skeleton bone poses for character animation
• game_ui_theme - Apply color, constant, and font size theme overrides
• game_viewport - Create/configure SubViewport nodes
• game_debug_draw - Draw debug geometry (lines, spheres, boxes)

Networking

• game_http_request - HTTP GET/POST/PUT/DELETE with headers and body
• game_websocket - WebSocket client connect/disconnect/send messages
• game_multiplayer - ENet multiplayer create server/client/disconnect
• game_rpc - Call or configure RPC methods on nodes

System & Window Control

• game_script - Attach, detach, or get source of node scripts at runtime
• game_window - Get/set window size, fullscreen, title, position
• game_os_info - Get platform, locale, screen, adapter, memory info
• game_time_scale - Get/set Engine.time_scale and timing info
• game_process_mode - Set node process mode (pausable/always/disabled)
• game_world_settings - Get/set gravity, physics FPS, and world settings

Advanced Signals & Input

• game_list_signals - List all signals on a node with connections
• game_await_signal - Await a signal with timeout and return args
• game_touch - Simulate touch press/release/drag and gestures
• game_input_state - Query pressed keys, mouse position, connected pads
• game_input_action - Manage runtime InputMap actions and strength

3D Rendering & Geometry

• game_csg - Create/configure CSG nodes with boolean operations
• game_multimesh - Create/configure MultiMeshInstance3D for instancing
• game_procedural_mesh - Generate meshes via ArrayMesh from vertex data
• game_light_3d - Create/configure 3D lights (directional/omni/spot)
• game_mesh_instance - Create MeshInstance3D with primitive meshes
• game_gridmap - GridMap set/get/clear cells and query used cells
• game_3d_effects - Create ReflectionProbe, Decal, or FogVolume
• game_gi - Create/configure VoxelGI or LightmapGI
• game_path_3d - Create Path3D/Curve3D and manage curve points
• game_sky - Create/configure Sky with procedural/physical sky
• game_camera_attributes - Configure DOF, exposure, auto-exposure on camera
• game_navigation_3d - Create/configure NavigationRegion3D and bake
• game_physics_3d - Area3D queries and point/shape intersection tests

2D Systems

• game_canvas - Create/configure CanvasLayer and CanvasModulate
• game_canvas_draw - 2D drawing: line/rect/circle/polygon/text/clear
• game_light_2d - Create/configure 2D lights and light occluders
• game_parallax - Create/configure ParallaxBackground and layers
• game_shape_2d - Line2D/Polygon2D point manipulation
• game_path_2d - Path2D/Curve2D management and AnimatedSprite2D
• game_physics_2d - Area2D queries and 2D point/shape intersections

Advanced Animation

• game_animation_tree - AnimationTree state machine travel and params
• game_animation_control - AnimationPlayer seek/queue/speed/info control
• game_skeleton_ik - SkeletonIK3D start/stop/set target position

Advanced Audio

• game_audio_effect - Add/remove/configure audio bus effects
• game_audio_bus_layout - Create/remove/reorder audio buses and routing
• game_audio_spatial - Configure AudioStreamPlayer3D spatial properties

Editor & Project Tools

• rename_file - Rename or move a file within the project
• manage_resource - Read or modify .tres/.res resource files
• create_script - Create a GDScript file from a template
• manage_scene_signals - List/add/remove signal connections in .tscn files
• manage_layers - List/set named layer definitions in project
• manage_plugins - List/enable/disable editor plugins
• manage_shader - Create or read .gdshader files
• manage_theme_resource - Create/read/modify Theme .tres resources
• set_main_scene - Set the main scene in project.godot
• manage_scene_structure - Rename/duplicate/move nodes within .tscn scenes
• manage_translations - List/add/remove translation files in project
• game_locale - Set/get locale and translate strings at runtime

UI Controls

• game_ui_control - Set focus, anchors, tooltip, mouse filter on Control
• game_ui_text - LineEdit/TextEdit/RichTextLabel text operations
• game_ui_popup - Show/hide/popup for Popup/Dialog/Window nodes
• game_ui_tree - Tree control: get/select/collapse/add/remove items
• game_ui_item_list - ItemList/OptionButton: get/select/add/remove items
• game_ui_tabs - TabContainer/TabBar: get/set current tab
• game_ui_menu - PopupMenu/MenuBar: add/remove/get menu items
• game_ui_range - ProgressBar/Slider/SpinBox/ColorPicker get/set

Rendering & Resources

• game_render_settings - Get/set MSAA, FXAA, TAA, scaling mode/scale
• game_resource - Runtime resource load, save, or preload

Robustness Improvements

• Reentrancy guard - Prevents concurrent command processing during async operations
• Full type conversion - Supports Vector2/3, Color, Quaternion, Basis, Transform2D/3D, AABB, Rect2, and all packed array types
• Smart property type detection - Uses node's get_property_list() for automatic type conversion
• PackedArray serialization - Proper JSON arrays instead of string fallback
• Graceful error handling - Scene read fallback to raw .tscn text on missing dependencies

All 149 Tools

Project Management (7 tools)

| Tool | Description | |------|-------------| | launch_editor | Launch Godot editor for a project | | run_project | Run a Godot project and capture output | | stop_project | Stop the running project | | get_debug_output | Get console output and errors | | get_godot_version | Get installed Godot version | | list_projects | Find Godot projects in a directory | | get_project_info | Get project metadata |

Scene Management (7 tools)

| Tool | Description | |------|-------------| | create_scene | Create a new scene with a root node type | | add_node | Add a node to an existing scene | | load_sprite | Load a texture into a Sprite2D node | | export_mesh_library | Export a scene as MeshLibrary | | save_scene | Save a scene (with optional variant path) | | get_uid | Get UID for a file (Godot 4.4+) | | update_project_uids | Resave resources to update UIDs |

Headless Scene Operations (5 tools)

| Tool | Description | |------|-------------| | read_scene | Read full scene tree as JSON | | modify_scene_node | Modify node properties in a scene file | | remove_scene_node | Remove a node from a scene file | | attach_script | Attach a GDScript to a scene node | | create_resource | Create a .tres resource file |

Project Settings (3 tools)

| Tool | Description | |------|-------------| | read_project_settings | Parse project.godot as JSON | | modify_project_settings | Change a project setting | | list_project_files | List/filter project files |

Runtime Input (4 tools)

| Tool | Description | |------|-------------| | game_screenshot | Capture a screenshot (base64 PNG) | | game_click | Click at a position | | game_key_press | Send key press or input action | | game_mouse_move | Move the mouse |

Runtime Inspection (3 tools)

| Tool | Description | |------|-------------| | game_get_ui | Get all visible UI elements | | game_get_scene_tree | Get full scene tree structure | | game_get_node_info | Detailed node introspection |

Runtime Code Execution (1 tool)

| Tool | Description | |------|-------------| | game_eval | Execute arbitrary GDScript with return values |

Runtime Node Manipulation (7 tools)

| Tool | Description | |------|-------------| | game_get_property | Get any node property | | game_set_property | Set any node property (auto type conversion) | | game_call_method | Call any method on a node | | game_instantiate_scene | Add a PackedScene to the running tree | | game_remove_node | Remove a node from the tree | | game_change_scene | Switch to a different scene | | game_reparent_node | Move a node to a new parent |

Runtime Signals (5 tools)

| Tool | Description | |------|-------------| | game_connect_signal | Connect a signal to a method | | game_disconnect_signal | Disconnect a signal | | game_emit_signal | Emit a signal with arguments | | game_list_signals | List all signals on a node with connections | | game_await_signal | Await a signal with timeout and return args |

Runtime Animation (2 tools)

| Tool | Description | |------|-------------| | game_play_animation | Control AnimationPlayer | | game_tween_property | Tween a property with easing |

Runtime Utilities (5 tools)

| Tool | Description | |------|-------------| | game_pause | Pause/unpause the game | | game_performance | Get FPS, memory, draw calls | | game_wait | Wait N frames | | game_get_nodes_in_group | Query nodes by group | | game_find_nodes_by_class | Find nodes by class type |

File I/O (4 tools)

| Tool | Description | |------|-------------| | read_file | Read a text file from a Godot project | | write_file | Create or overwrite a text file | | delete_file | Delete a file from a project | | create_directory | Create a directory inside a project |

Error & Log Capture (2 tools)

| Tool | Description | |------|-------------| | game_get_errors | Get new errors/warnings since last call | | game_get_logs | Get new print output since last call |

Enhanced Input (8 tools)

| Tool | Description | |------|-------------| | game_key_hold | Hold a key down (no auto-release) | | game_key_release | Release a held key | | game_scroll | Mouse scroll wheel event | | game_mouse_drag | Drag between two points over N frames | | game_gamepad | Gamepad button or axis input | | game_touch | Simulate touch press/release/drag and gestures | | game_input_state | Query pressed keys, mouse position, connected pads | | game_input_action | Manage runtime InputMap actions and strength |

Project Creation (4 tools)

| Tool | Description | |------|-------------| | `create_proje

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tugcantopaloglu
• Source: tugcantopaloglu/godot-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.