Godot AI MCP Server

An enhanced Model Context Protocol (MCP) server for the Godot game engine. Provides AI assistants with tools to launch the editor, run projects, manipulate scenes, manage scripts, and control node properties — all through a standardized MCP interface.

Based on @coding-solo/godot-mcp by Solomon Elias. That project provides the original core tools (launch editor, run project, scene management, UID tools). This fork adds script manipulation (set_script, read_script, write_script, list_scripts), scene inspection (get_scene_tree), node removal (remove_node), and property editing (set_node_property).

Original project: Coding-Solo/godot-mcp — MIT License.

Features

Core Tools

• launch_editor — Open the Godot editor for a project
• run_project — Run a Godot project in debug mode
• get_debug_output — Capture stdout/stderr from running projects
• stop_project — Stop a running project
• get_godot_version — Check installed Godot version
• list_projects — Find Godot projects in a directory
• get_project_info — Get project metadata (scene count, script count, etc.)

Scene Management

• create_scene — Create new scene files with any root node type
• add_node — Add nodes to existing scenes with properties
• remove_node — Remove nodes from scenes
• get_scene_tree — Inspect the full scene tree structure
• load_sprite — Load textures into Sprite2D/Sprite3D/TextureRect nodes
• export_mesh_library — Export 3D scenes as MeshLibrary for GridMap
• save_scene — Save/repack scene files

Script Tools

• set_script — Attach a script to a node (creates the script if it doesn't exist)
• read_script — Read .gd, .cs, or .shader file contents
• write_script — Create or overwrite script files
• list_scripts — List all scripts in a project

Node Properties

• set_node_property — Set any property on a node in a scene

UID Management (Godot 4.4+)

• get_uid — Get UID for a specific file
• update_project_uids — Resave all resources to update UID references

Requirements

• Node.js >= 18.0.0
• Godot 4.x (Mono build recommended for C# support)

Installation

npm install -g /path/to/godot-ai-mcp

Or use directly via npx:

npx /path/to/godot-ai-mcp

Configuration

MCP Config (opencode.json, claude desktop, etc.)

{
  "mcp": {
    "godot-ai": {
      "type": "local",
      "command": [
        "env",
        "GODOT_PATH=/path/to/your/godot/executable",
        "DEBUG=true",
        "npx",
        "-y",
        "godot-ai-mcp"
      ]
    }
  }
}

Environment Variables

Variable	Description
GODOT_PATH	Path to the Godot executable (auto-detected if not set)
DEBUG	Set to true for verbose debug output on stderr

Usage Examples

Create a scene with a Player node and attach a script

1. create_scene(projectPath="/path/to/project", scenePath="scenes/player.tscn", rootNodeType="CharacterBody2D")
2. add_node(projectPath="/path/to/project", scenePath="scenes/player.tscn", parentNodePath="root", nodeType="Sprite2D", nodeName="Sprite")
3. set_script(projectPath="/path/to/project", scenePath="scenes/player.tscn", nodePath="root", scriptPath="scripts/player.gd")
4. load_sprite(projectPath="/path/to/project", scenePath="scenes/player.tscn", nodePath="root/Sprite", texturePath="assets/player.png")

Inspect and modify a scene

1. get_scene_tree(projectPath="/path/to/project", scenePath="scenes/level.tscn")
2. set_node_property(projectPath="/path/to/project", scenePath="scenes/level.tscn", nodePath="root/Enemy", propertyName="position", propertyValue=[100, 200])
3. remove_node(projectPath="/path/to/project", scenePath="scenes/level.tscn", nodePath="root/DebugNode")

Script workflow

1. list_scripts(projectPath="/path/to/project")
2. read_script(projectPath="/path/to/project", scriptPath="scripts/enemy.gd")
3. write_script(projectPath="/path/to/project", scriptPath="scripts/enemy.gd", content="extends CharacterBody2D\n...")

Building from Source

npm install
npm run build

The compiled output goes to build/. The GDScript file is copied to build/scripts/.

License

MIT — see LICENSE for details.

This project is derived from @coding-solo/godot-mcp (MIT, © Solomon Elias). The original core server architecture, GDScript headless operations pattern, and scene manipulation tools are based on that project.