Godot-MCP-Pilot

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.

Demo

"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-pilot

Or use without installing:

npx godot-mcp-pilot

2. Run the setup wizard

npx godot-mcp-pilot setup
# or, if installed globally:
godot-mcp-pilot-setup

The 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

Manual Setup

Claude Code (CLI / IDE extension)

Critical: Claude Code reads .mcp.json from 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-pilot

This writes .mcp.json to your current directory. Then always launch Claude Code from that directory:

cd ~/games/my-platformer
claude

If 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-pilot

Or 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	`/Applications/Godot.app`, `/Applications/Godot_4.app`, versioned names like `Godot_v4.3.app`, `~/Applications/...`, `~/Downloads/...`, Homebrew
Linux	`/usr/bin/godot`, `/usr/local/bin/godot`, `/snap/bin/godot`, `~/.local/bin/godot`
Windows	`C:\Program Files\Godot\Godot.exe`, `%LOCALAPPDATA%\Godot\Godot.exe`

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	`CharacterBody2D`	`CharacterBody3D`
Root	`Node2D`	`Node3D`
Camera	`Camera2D`	`Camera3D`
Mesh	`Sprite2D`	`MeshInstance3D`
Collision	`CollisionShape2D`	`CollisionShape3D`
Physics	`RigidBody2D`	`RigidBody3D`
Light	—	`DirectionalLight3D`, `OmniLight3D`

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	`get_godot_version`, `list_projects`, `get_project_info`
Editor / Run	`launch_editor`, `run_project`, `stop_project`, `get_debug_output`, `run_gdscript`
Scenes	`list_project_scenes`, `read_scene`, `create_scene`, `save_scene`
Nodes	`add_node`, `edit_node`, `remove_node`, `duplicate_node`, `move_node`, `load_sprite`, `instantiate_scene`
Scripts	`list_project_scripts`, `read_script`, `create_script`, `modify_script`, `analyze_script`, `list_script_functions`, `add_script_function`, `remove_script_function`, `add_signal`, `add_variable`
Project	`get_project_settings`, `set_project_setting`, `get_main_scene`, `set_main_scene`, `list_autoloads`, `add_autoload`, `remove_autoload`, `list_input_actions`, `add_input_action`, `remove_input_action`
Assets	`list_assets`, `get_asset_info`
UIDs	`get_uid`, `update_project_uids`

Configuration

Environment Variable	Default	Description
`GODOT_PATH`	auto-detected	Absolute path to the Godot executable
`READ_ONLY_MODE`	`false`	If `true`, disables all modifying tools (safe for CI/review)
`DEBUG`	`false`	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/Godot

To find where Godot is:

# macOS / Linux
find ~/Downloads ~/Applications /Applications -name "Godot" -type f 2>/dev/null

Scene 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>&1

MCP 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-pilot

Disables 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 dev

Project 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 ops

Compatibility

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_editor and run_project only start processes with safe, predefined args
Use READ_ONLY_MODE=true in untrusted environments
The server never executes arbitrary shell commands — only the Godot binary

License

MIT

This site is open source. Improve this page.