godot-mcp-pilot
Exposes Godot engine operations as MCP tools, allowing AI assistants to manipulate Godot projects programmatically including scene creation/editing, script management, project execution, and asset inspection for game development workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@godot-mcp-pilot create a 2D player character with sprite and collision"
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.
godot-mcp-pilot
Model Context Protocol server for Godot 4 — Give AI assistants (Claude, Cursor, Cline, etc.) direct control over your Godot projects.
godot-mcp-pilot exposes Godot engine operations as MCP tools, letting AI assistants launch the editor, run projects, create and edit scenes, write GDScript, and inspect assets — all through natural language. Works for both 2D and 3D games.

"Create a CharacterBody3D player scene with a Camera3D and collision"
"Run the project and show me any errors"
"Add a DirectionalLight3D to the scene"
"Create a 2D platformer with sprites and tilemaps"Quick Start
1. Install
npm install -g godot-mcp-pilotOr use without installing:
npx godot-mcp-pilot2. Run the setup wizard
npx godot-mcp-pilot setup
# or, if installed globally:
godot-mcp-pilot-setupThe wizard will:
Auto-detect your Godot binary (checks Applications, Downloads, PATH)
Ask which AI client you use
Write the config to the right place for that client
Related MCP server: Godot MCP Enhanced
Manual Setup
Claude Code (CLI / IDE extension)
Critical: Claude Code reads
.mcp.jsonfrom the directory where you launch it.
The file must be in your game project folder, not the godot-mcp-pilot folder.
# From inside your game project directory:
claude mcp add godot -- npx godot-mcp-pilotThis writes .mcp.json to your current directory. Then always launch Claude Code from that directory:
cd ~/games/my-platformer
claudeIf Godot isn't auto-detected (e.g. you never moved it out of ~/Downloads):
claude mcp add godot -e GODOT_PATH=/path/to/Godot.app/Contents/MacOS/Godot -- npx godot-mcp-pilotOr write .mcp.json manually in your game project root:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["godot-mcp-pilot"],
"env": {
"GODOT_PATH": "/path/to/your/Godot"
}
}
}
}Claude Desktop
Claude Desktop uses a different config file — it does not read .mcp.json.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["godot-mcp-pilot"],
"env": {
"GODOT_PATH": "/path/to/your/Godot"
}
}
}
}Then quit and reopen Claude Desktop.
Cursor (.cursor/mcp.json)
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["godot-mcp-pilot"],
"env": {
"GODOT_PATH": "/path/to/your/Godot"
}
}
}
}Godot Path Detection
The server searches these locations automatically (in order):
OS | Paths checked |
macOS |
|
Linux |
|
Windows |
|
If auto-detection fails, set GODOT_PATH to the absolute path of your Godot executable.
2D and 3D Games
godot-mcp-pilot works equally well for 2D and 3D. Use the appropriate node types:
2D | 3D | |
Player |
|
|
Root |
|
|
Camera |
|
|
Mesh |
|
|
Collision |
|
|
Physics |
|
|
Light | — |
|
Example prompts:
"Create a 3D scene with a Node3D root, MeshInstance3D floor, and DirectionalLight3D"
"Add a CharacterBody3D with a CollisionShape3D using a CapsuleShape3D"
"Write a GDScript for 3D first-person movement"Features
Category | Tools |
System |
|
Editor / Run |
|
Scenes |
|
Nodes |
|
Scripts |
|
Project |
|
Assets |
|
UIDs |
|
Configuration
Environment Variable | Default | Description |
| auto-detected | Absolute path to the Godot executable |
|
| If |
|
| Print debug info to stderr |
Troubleshooting
"MCP server not connected" / tools not appearing
Claude Code: The .mcp.json must be in the directory where you run claude. Open a new terminal, cd into your game project, and run claude from there.
Claude Desktop: Make sure you edited the right file (claude_desktop_config.json, not .mcp.json) and fully quit and reopened the app.
Godot not found
Set GODOT_PATH explicitly in the config env block. On macOS, if you downloaded Godot but never moved it:
GODOT_PATH=/Users/yourname/Downloads/Godot.app/Contents/MacOS/GodotTo find where Godot is:
# macOS / Linux
find ~/Downloads ~/Applications /Applications -name "Godot" -type f 2>/dev/nullScene parse errors / malformed .tscn
If Godot refuses to load a scene edited by the MCP, check that instance= lines are unquoted:
# Correct
instance=ExtResource("1_abc")
# Wrong (Godot rejects this)
instance="ExtResource(\"1_abc\")"Run the project headless to see the exact error:
/path/to/Godot --path /path/to/project --headless --quit 2>&1MCP disconnects during a session
This is a known issue with some MCP host implementations. Workaround: close and reopen your AI client. The MCP server itself is stateless — reconnecting is safe.
Example Workflows
2D top-down shooter
"Create a 2D scene called Main.tscn"
"Add a CharacterBody2D called Player at the center"
"Create a movement + shooting script for the Player"
"Add an Area2D called Enemy that moves toward the player"
"Run the project and show errors"3D platformer
"Create a 3D scene with a StaticBody3D floor (MeshInstance3D box, scale 20x1x20)"
"Add a CharacterBody3D player with a CapsuleShape3D collision"
"Create a 3D character controller script with jump and gravity"
"Add a Camera3D as a child of the player with offset Vector3(0, 2, 5)"Read-Only Mode
READ_ONLY_MODE=true npx godot-mcp-pilotDisables all write tools. Useful for CI/CD or review workflows.
Development
git clone https://github.com/pushks18/godot-mcp-pilot
cd godot-mcp-pilot
npm install
npm run build
# Run the setup wizard
npm run setup
# Development mode (ts-node, no build step)
npm run devProject Structure
godot-mcp-pilot/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server + tool routing
│ ├── config.ts # Godot path detection, env config
│ ├── godot-process.ts # Process management (spawn, capture)
│ ├── tools/
│ │ ├── system.ts # Version, project listing/info
│ │ ├── execution.ts # Launch editor, run/stop project
│ │ ├── scene.ts # Scene CRUD + node manipulation
│ │ ├── script.ts # GDScript read/write/analyze
│ │ ├── assets.ts # Asset listing/inspection
│ │ ├── project_settings.ts # Settings, autoloads, input maps
│ │ └── uid.ts # Godot 4 UID management
│ └── utils/
│ ├── path.ts # Path validation (prevents traversal)
│ ├── tscn.ts # .tscn parser and serializer
│ └── project_godot.ts # project.godot reader
└── scripts/
├── setup.js # Interactive setup wizard
└── godot_operations.gd # Bundled GDScript for runtime opsCompatibility
Godot 4.x (primary target — tested on 4.2, 4.3, 4.4)
Godot 3.x — basic tools work; scene format differences apply
MCP Protocol — 2024-11-05 spec
Node.js — 18+
Security
All file paths are validated to stay within the project directory (no path traversal)
launch_editorandrun_projectonly start processes with safe, predefined argsUse
READ_ONLY_MODE=truein untrusted environmentsThe server never executes arbitrary shell commands — only the Godot binary
License
MIT
Available Tools
44 toolsadd_autoloadB
Add or update an autoload (singleton) in the project settings. The script will be instantiated automatically when the project starts.
Inputs: projectPath (required), name (required), scriptPath (required), enabled.
add_input_actionB
Add a new input action to the project's Input Map (with no events bound). Use the Godot editor or set_project_setting to bind keys to it.
Inputs: projectPath (required), actionName (required).
add_nodeC
Add a new node to an existing scene.
Inputs: projectPath (required), scenePath (required), nodeType (required), nodeName (required), +2 more.
add_script_functionA
Append a new function to a GDScript file. Fails if the function already exists.
Inputs: projectPath (required), scriptPath (required), funcName (required), body (required), +3 more.
add_signalC
Add a signal declaration to a GDScript file. Inserted after existing signals.
Inputs: projectPath (required), scriptPath (required), signalName (required), params.
add_variableB
Add a top-level variable or property declaration to a GDScript file.
Inputs: projectPath (required), scriptPath (required), varName (required), type, +2 more.
analyze_scriptB
Perform basic static analysis on a GDScript file — finds common errors and Godot 4 migration issues.
Inputs: projectPath (required), scriptPath (required).
create_sceneB
Create a new .tscn scene file with a specified root node type.
Inputs: projectPath (required), scenePath (required), rootNodeType.
create_scriptB
Create a new GDScript file. Use the template param to pick a starter template: 'CharacterBody2D', 'CharacterBody3D', 'Singleton', or provide custom content.
Inputs: projectPath (required), scriptPath (required), template.
duplicate_nodeA
Duplicate a node (and its children) within the same scene, giving it a new name. The duplicate is placed under the same parent as the original.
Inputs: projectPath (required), scenePath (required), nodePath (required), newName (required).
edit_nodeC
Modify properties of an existing node in a scene.
Inputs: projectPath (required), scenePath (required), nodePath (required), properties (required).
get_asset_infoB
Get detailed metadata about a specific asset: type, size, UID, and import settings.
Inputs: projectPath (required), assetPath (required).
get_debug_outputB
Get console output (stdout/stderr) from the running or last run project.
Inputs: no named parameters.
get_godot_versionA
Get the installed Godot engine version and platform information.
Inputs: no named parameters.
get_main_sceneB
Get the project's configured main (startup) scene path.
Inputs: projectPath (required).
get_project_infoB
Get metadata about a Godot project: name, version, scene/script/asset counts.
Inputs: projectPath (required).
get_project_settingsA
Read the project.godot configuration. Optionally filter to a specific section (e.g. "application", "display", "input", "autoload", "rendering").
Inputs: projectPath (required), section.
get_uidB
Get the Godot 4 unique ID (uid://) for a resource file.
Inputs: projectPath (required), filePath (required).
instantiate_sceneB
Instantiate a packed scene (sub-scene) as a child node inside another scene. Adds the ext_resource entry automatically.
Inputs: projectPath (required), scenePath (required), subScenePath (required), parentNodePath, +1 more.
launch_editorA
Open the Godot editor for a project. Non-blocking — returns immediately.
Inputs: projectPath (required).
list_assetsB
List all asset files in a project (textures, audio, meshes, fonts, shaders, etc.). Optionally filter by type.
Inputs: projectPath (required), assetType.
list_autoloadsB
List all autoload (singleton) entries configured in the project.
Inputs: projectPath (required).
list_input_actionsB
List all custom input actions defined in the project (Project > Project Settings > Input Map).
Inputs: projectPath (required).
list_projectsC
Find Godot projects (project.godot files) under a directory.
Inputs: directory (required), recursive.
list_project_scenesC
List all .tscn scene files in a project.
Inputs: projectPath (required).
list_project_scriptsB
List all GDScript (.gd) files in a project.
Inputs: projectPath (required).
list_script_functionsA
Parse a GDScript file and return all functions, signals, and top-level variables with their names, parameters, return types, and line numbers.
Inputs: projectPath (required), scriptPath (required).
load_spriteC
Load a texture resource into a Sprite2D (or TextureRect) node.
Inputs: projectPath (required), scenePath (required), nodePath (required), texturePath (required).
modify_scriptC
Overwrite a GDScript file with new content.
Inputs: projectPath (required), scriptPath (required), newContent (required).
move_nodeA
Move (re-parent) a node to a different parent within the same scene. All descendant parent paths are updated automatically.
Inputs: projectPath (required), scenePath (required), nodePath (required), newParentPath (required).
read_sceneB
Read a scene file — returns raw .tscn text and a structured node list.
Inputs: projectPath (required), scenePath (required).
read_scriptB
Read the source code of a GDScript file.
Inputs: projectPath (required), scriptPath (required).
remove_autoloadC
Remove an autoload singleton from the project settings.
Inputs: projectPath (required), name (required).
remove_input_actionC
Remove an input action from the project's Input Map.
Inputs: projectPath (required), actionName (required).
remove_nodeB
Remove a node (and all its children) from a scene.
Inputs: projectPath (required), scenePath (required), nodePath (required).
remove_script_functionC
Remove a function and its entire body from a GDScript file.
Inputs: projectPath (required), scriptPath (required), funcName (required).
run_gdscriptA
Run a GDScript snippet headlessly inside a project and return the output. The script body is wrapped in a SceneTree subclass automatically — just write the statements to execute (e.g. print("hello")). Great for quick tests and calculations that need Godot's built-in types.
Inputs: projectPath (required), scriptBody (required), timeoutMs.
run_projectA
Run a Godot project in debug mode (background). Optionally run a specific scene. Use get_debug_output to retrieve console logs after starting.
Inputs: projectPath (required), scene.
save_sceneC
Save a scene (re-writes it to disk, optionally to a new path).
Inputs: projectPath (required), scenePath (required), newPath.
set_main_sceneC
Set the project's main (startup) scene.
Inputs: projectPath (required), scenePath (required).
set_project_settingA
Write a setting to project.godot. The value must be a valid Godot config value string. For strings, wrap in double quotes: e.g. value='"res://scene.tscn"'. For booleans/numbers use: 'true', '42'. Creates the section if it doesn't exist.
Inputs: projectPath (required), section (required), key (required), value (required).
set_scene_scriptA
Attach a GDScript to a node in a scene, or detach the current script. Automatically adds the ext_resource entry to the .tscn file.
Inputs: projectPath (required), scenePath (required), nodePath (required), scriptPath.
stop_projectA
Stop the currently running Godot project.
Inputs: no named parameters.
update_project_uidsA
Re-import all project assets to refresh Godot 4 UIDs. Runs Godot headlessly. Use after adding or moving resource files.
Inputs: projectPath (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 44 tools
Every tool has a clearly distinct purpose with no ambiguity. Tools are well-organized into categories like project management, scene editing, script manipulation, and asset handling, making it easy for an agent to select the correct tool for each task without confusion.
All tool names follow a consistent verb_noun pattern with snake_case throughout, such as 'add_autoload', 'create_scene', and 'get_project_info'. This predictability enhances readability and usability for agents.
With 44 tools, the count is borderline high for the Godot domain, which could feel heavy and overwhelming. While the tools cover many aspects comprehensively, the large number may increase complexity for agents in navigation and selection.
The tool set provides complete CRUD/lifecycle coverage for Godot project management, including project setup, scene and script editing, asset handling, and runtime operations. There are no obvious gaps, ensuring agents can handle all core workflows without dead ends.
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.333MIT
- AlicenseBqualityDmaintenanceAn enhanced MCP server for interacting with the Godot game engine, enabling AI assistants to launch the editor, run projects, manage scenes and nodes, and handle scripts.16MIT
- AlicenseCqualityCmaintenanceAn 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.10098 npm515MIT
- AlicenseAqualityDmaintenanceAn MCP server that gives AI assistants full control over the Godot game engine, enabling scene building, script writing, game running, and more through natural language.75187 npm8MIT