You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A comprehensive Model Context Protocol (MCP) server that gives AI assistants full control over the Godot game engine. 157 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 157 tools with the following major additions:
New in 3.1
validate_script autoload resolution - Script validation now compiles the target through a SceneTree at _initialize() (after project autoloads are registered) instead of --check-only at _init(). References to autoload singletons no longer produce false Identifier not found errors, while real syntax/type errors are still caught. Verified building a full game whose scripts reference several autoloads.
manage_input_map event merging - Adding a second key to an existing input action now merges it into that action's events array (with physical_keycode de-duplication) instead of writing a duplicate actionname= line, which previously left project.godot malformed and silently dropped earlier bindings.
New in 3.0
.NET / C# support - Scaffold C# projects and generate C# scripts (create_project with dotnet: true, create_csharp_script); the .csproj SDK version is matched to your installed Godot.
GDScript diagnostics - Validate scripts for syntax and type errors without running the game (validate_script, and validate_scripts for all git-changed or project-wide files).
Correctness and robustness fixes across the headless scene operations and the runtime interaction server (resource-typed properties now persist, reparenting works, runtime commands are correlated by request id, and the tools survive projects with warnings-as-errors). Requires Godot 4.4 or later; tested and working with the latest Godot 4.7.
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
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 push_error/push_warning 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 (pass dotnet: true to scaffold a .NET/C# project)
create_csharp_script - Create a C# script in a Godot .NET project
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
.NET / C# Support
create_project with dotnet: true - Scaffold a Godot .NET project (.csproj with Godot.NET.Sdk matched to your Godot version, plus the "C#" feature flag)
create_csharp_script - Generate an idiomatic C# script (partial class, correct _Ready/_Process override signatures); the class name is kept in sync with the file name so Godot can attach it
get_project_info reports an isDotnet field
GDScript Diagnostics
validate_script - Check a single GDScript file for syntax and type errors headlessly, returning { valid, errors: [{ message, file, line }] }
validate_scripts - Batch-validate all git-changed .gd files (or the whole project), so an agent can verify its edits before running the game
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
To use the game_* runtime tools, your Godot project needs the MCP interaction server autoload. Copy build/scripts/mcp_interaction_server.gd to your project and register it as an autoload:
Copy build/scripts/mcp_interaction_server.gd to your project's scripts folder
In Godot: Project > Project Settings > Autoload
Add the script with the name McpInteractionServer
The server listens on 127.0.0.1:9090 and accepts JSON commands over TCP when the game is running.
Environment Variables
Variable
Description
GODOT_PATH
Path to the Godot executable (overrides auto-detection)
DEBUG
Set to "true" for detailed server-side logging
GODOT_MCP_ALLOWED_DIRS
Optional. Restrict run_project to projects under these roots (;, ,, or : separated). When unset, any project path is allowed.
Architecture
The server uses two communication channels:
Headless CLI - For operations that don't need a running game (scene reading, modification, resource creation). Runs Godot with --headless --script godot_operations.gd <operation> <json_params>.
TCP Socket - For runtime interaction with a running game. The mcp_interaction_server.gd autoload listens on port 9090 and processes JSON commands sent by the TypeScript MCP server.
Source layout
Path
Description
src/index.ts
MCP server, tool definitions, and all handlers
src/utils.ts
Pure utility functions (parameter mapping, validation, error helpers)
src/scripts/godot_operations.gd
Headless GDScript operations runner
src/scripts/mcp_interaction_server.gd
TCP interaction server autoload
tests/
Vitest test suite
Testing
The project uses Vitest with 446 tests across 5 files:
File
Tests
What it covers
tests/utils.test.ts
31
Parameter mappings, normalization, path validation, error responses, version detection
npm test# run once
npm run test:watch # watch mode
Example Prompts
"Run my Godot project and check for errors"
"Eval this in my running game: return get_tree().current_scene.name"
"Get the player's position in the running game"
"Set the player's health to 100"
"Read the test_level.tscn scene and show me the node tree"
"Change the player's speed property in the player.tscn scene file"
"List all .gd files in my project"
"Connect the enemy's 'died' signal to the game manager's 'on_enemy_died' method"
"Tween the camera's position to (0, 10, -5) over 2 seconds with ease-out"
"Get performance metrics - what's my FPS and draw call count?"
"Pause the game and take a screenshot"
"Find all CharacterBody3D nodes in the scene"
"Create a new Godot project called 'MyGame' and write a player script"
"Create a new C# (.NET) Godot project and add a CharacterBody2D script"
"Validate player.gd for errors"
"Check all my changed GDScript files for syntax errors before I run the game"
"Hold down the W key for 2 seconds to test walking"
"Cast a ray from the player downward to check for ground"
"Get the camera position and move it to look at the player"
"Show me the latest error messages from the running game"
License
This project is licensed under the MIT License - see the LICENSE file for details.
Credits
Original project: godot-mcp by Solomon Elias (Coding-Solo) - provided the foundational MCP server architecture, headless operations system, and TCP interaction framework
Extended by: Tugcan Topaloglu - extended to 157 tools covering networking, 3D/2D rendering, UI controls, audio effects, animation trees, file I/O, runtime code execution, node manipulation, signals, project creation, camera control, physics, and comprehensive type conversion
About
MCP server for full Godot 4.x engine control: 157 tools for AI-driven game development (GDScript and C#/.NET). Tested with Godot 4.7.
