Skip to main content
Glama

godot-mcp-pilot

Model Context Protocol server for Godot 4 — Give AI assistants (Claude, Cursor, Cline, etc.) direct control over your Godot projects.

npm version License: MIT Docs CI

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


Related MCP server: Godot MCP Enhanced

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

Available Tools

44 tools
add_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

    A3.5/5.0

    Scored across 44 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • 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.
      33
      3
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      An 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.
      16
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      75
      187 npm
      8
      MIT