godot-mcp-extended

Originally based on Coding-Solo/godot-mcp by Solomon Elias (MIT). Independently developed as godot-mcp-extended since v0.2.0.

                           (((((((             (((((((
                        (((((((((((           (((((((((((
                        (((((((((((((       (((((((((((((
                        (((((((((((((((((((((((((((((((((
                        (((((((((((((((((((((((((((((((((
         (((((      (((((((((((((((((((((((((((((((((((((((((      (((((
       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
     ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
    ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
        (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
         (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((
         (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((
         (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((
         ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
         @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@
         ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((
         (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((
          (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((
           (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
              (((((((((((((((((((((((((((((((((((((((((((((((((((((
                 (((((((((((((((((((((((((((((((((((((((((((((((
                        (((((((((((((((((((((((((((((((((


                          /$$      /$$  /$$$$$$  /$$$$$$$
                         | $$$    /$$$ /$$__  $$| $$__  $$
                         | $$$$  /$$$$| $$  \__/| $$  \ $$
                         | $$ $$/$$ $$| $$      | $$$$$$$/
                         | $$  $$$| $$| $$      | $$____/
                         | $$\  $ | $$| $$    $$| $$
                         | $$ \/  | $$|  $$$$$$/| $$
                         |__/     |__/ \______/ |__/

A Model Context Protocol (MCP) server for interacting with the Godot game engine.

Introduction

Godot MCP enables AI agents to launch the Godot editor, run projects, capture debug output, and control project execution. This direct feedback loop helps agents understand what works and what doesn't in real Godot projects, leading to better code generation and debugging assistance.

Related MCP server: Godot MCP

Features

• Launch Godot Editor: Open the Godot editor for a specific project

• Run Godot Projects: Execute Godot projects in debug mode

• Capture Debug Output: Retrieve console output and error messages

• Control Execution: Start and stop Godot projects programmatically

• Get Godot Version: Retrieve the installed Godot version

• List Godot Projects: Find Godot projects in a specified directory

• Project Analysis: Get detailed information about project structure

• Scene Management:

  • Create new scenes with specified root node types

  • Add nodes to existing scenes with customizable properties

  • Load sprites and textures into Sprite2D nodes

  • Export 3D scenes as MeshLibrary resources for GridMap

  • Save scenes with options for creating variants

• UID Management (for Godot 4.4+):

  • Get UID for specific files

  • Update UID references by resaving resources

• .NET Diagnostics (extended):

  • dotnet_build with structured file/line/code compiler diagnostics

  • dotnet_test test runs with structured results

• Runtime observation & control (extended):

  • run_project_capture with [SIGNAL] markers and exit verdicts

  • Opt-in in-game hook (hook/signal_hook.gd) + hook_exec (tree|read|shot|quit|press|stats; shot returns path + base64)

• Scene inspection & editing (new):

  • dump_scene, list_assets, get_project_settings (no Godot run needed)

  • set_node_property, remove_node, rename_node, duplicate_node, instance_scene, create_script, attach_script, connect_signal

  • check_script (fast GDScript parse), run_tests, export_check

• Multi-host setup (extended): setup --host opencode|claude|codex|chatgpt|all

Requirements

• Godot Engine installed on your system

• Node.js (>=18.0.0) and npm

• An AI agent that supports MCP

Quick Start

Claude Code

claude mcp add godot -- npx godot-mcp-extended

That's it. Restart Claude Code and your Godot MCP tools are available.

With environment variables:

claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx godot-mcp-extended

opencode

Easiest — use the built-in installer (backs up your config first):

node build/index.js setup --host opencode --godot-path /path/to/godot

Then restart opencode. Or add manually to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "godot-mcp": {
      "command": ["node", "/path/to/godot-mcp-extended/build/index.js"],
      "enabled": true,
      "type": "local",
      "environment": { "GODOT_PATH": "/path/to/godot" },
      "timeout": 300000
    }
  }
}

ChatGPT desktop / Codex CLI

For Codex CLI, use the installer (appends a [mcp_servers.godot-mcp] table to ~/.codex/config.toml):

node build/index.js setup --host codex --godot-path /path/to/godot

For the ChatGPT desktop app, MCP config paths vary by version — run the installer for manual steps:

node build/index.js setup --host chatgpt --godot-path /path/to/godot

then add the printed command (node …/build/index.js with GODOT_PATH set) as a local MCP server and restart the app.

Runtime hook (opt-in)

run_project_capture observes games through [SIGNAL] log markers. For live inspection, install the optional in-game hook:

cp hook/signal_hook.gd /path/to/project/signal_hook.gd

then add to the project's project.godot:

[autoload]
SignalHook="*res://signal_hook.gd"

Restart the game via run_project; hook_exec can then run tree (subtree dump), read (read-only expression on a node, e.g. position), shot (viewport PNG), and quit (graceful exit).

Security boundary: the hook file is never installed automatically — you copy it yourself. It is dormant unless SIGNAL_HOOK=1 is in the environment (the sidecar sets it only for runs of projects containing the file). Commands are an allow-list (tree|read|shot|quit); read rejects sources containing set_, load(, OS., FileAccess, DirAccess, Engine, and friends, and the TCP server binds 127.0.0.1 only. Screenshots save inside the project under .signal/.

Add to your Cline MCP settings file (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-extended"],
      "env": {
        "DEBUG": "true"
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

Using the Cursor UI:

1. Go to Cursor Settings > Features > MCP

2. Click on the + Add New MCP Server button

3. Fill out the form:

   • Name: godot

   • Type: command

   • Command: npx godot-mcp-extended

4. Click "Add"

5. You may need to press the refresh button in the top right corner of the MCP server card to populate the tool list

Using Project-Specific Configuration:

Create a file at .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-extended"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

For any MCP-compatible client, use this configuration:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-extended"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}

Environment Variables

git clone https://github.com/daremau/godot-mcp-extended.git
cd godot-mcp-extended
npm install
npm run build

Then point your MCP client to build/index.js instead of using npx.

Architecture

The Godot MCP server uses a bundled GDScript approach for complex operations:

1. Direct Commands: Simple operations like launching the editor or getting project info use Godot's built-in CLI commands directly.

2. Bundled Operations Script: Complex operations like creating scenes or adding nodes use a single, comprehensive GDScript file (godot_operations.gd) that handles all operations.

The bundled script accepts operation type and parameters as JSON, allowing for flexible and dynamic operation execution without generating temporary files for each operation.

Troubleshooting

• Godot Not Found: Set the GODOT_PATH environment variable to your Godot executable path

• Connection Issues: Ensure the server is running and restart your AI assistant

• Invalid Project Path: Ensure the path points to a directory containing a project.godot file

• Build Issues: Make sure all dependencies are installed by running npm install

• Ensure the MCP server shows up and is enabled in Cursor settings (Settings > MCP)

• MCP tools can only be run using the Agent chat profile (Cursor Pro or Business subscription)

• Use "Yolo Mode" to automatically run MCP tool requests

License

This project is licensed under the MIT License - see the LICENSE file for details.