Godot MCP Assistant

Godot MCP Assistant is a local Model Context Protocol (MCP) server for Godot 4 projects. It lets AI clients such as Cursor, Claude Desktop, and OpenAI Codex inspect project settings, create GDScript and text-scene files, and communicate with the Godot editor.

The Node.js server communicates with MCP clients over stdio. Its file tools work while Godot is closed. An optional Godot editor add-on adds a loopback bridge for opening and running scenes and capturing the editor's 2D or 3D viewport.

Features

• create_gdscript — writes a GDScript file with a chosen base class. When source is omitted, it creates a starter script; CharacterBody2D and CharacterBody3D receive movement examples.

• generate_tscn_scene — converts a JSON scene tree into a Godot 4 .tscn file, including external resources, sub-resources, node properties, groups, and instanced scenes.

• analyze_project_godot — reads project.godot and returns the input map, enabled plugins, autoloads, global settings, parsed values, and original raw values.

• inject_script_autoload — adds an existing res:// GDScript as an Autoload singleton in project.godot.

• install_godot_editor_bridge — installs and enables the optional Godot editor add-on in a project.

• godot_editor_status, godot_open_scene, godot_play_scene, and godot_stop_scene — inspect and control the connected editor.

• capture_godot_viewport — returns a PNG image of the current Godot editor 2D or 3D viewport.

The tools expect the absolute path of a directory containing project.godot. Paths for files the server creates must be relative to that project directory.

Related MCP server: Godot MCP Server

Requirements

• Node.js 18 or newer

• A Godot 4 project with a project.godot file

• An MCP-compatible client that can launch a local stdio server

• Godot 4.0 or newer for editor bridge controls; viewport screenshots require Godot 4.2 or newer

Install

Clone this repository, then install its dependencies:

git clone https://github.com/YOUR-USERNAME/godot-mcp-assistant.git
cd godot-mcp-assistant
npm install

Run the server directly with:

npm start

The process waits for an MCP client on stdin and writes protocol messages to stdout. Do not add ordinary log output to stdout.

Connect the Godot editor

The file tools need no running Godot process. To open scenes, run or stop them, and capture editor viewport screenshots:

1. Connect this MCP server to your client.

2. Ask the assistant to call install_godot_editor_bridge with the target project's absolute projectPath. The tool copies the add-on into addons/godot_mcp_assistant, enables it in project.godot, and assigns a project-specific localhost port.

3. Open or restart the project in the Godot editor. If it was already open during installation, restart it so Godot loads the add-on. Call godot_editor_status to confirm the bridge is connected.

The bridge listens only on 127.0.0.1. Use godot_open_scene to open a scene, godot_play_scene to run it, and godot_stop_scene to stop it. Call capture_godot_viewport with viewport set to 2d or 3d to attach a PNG of the editor viewport to the tool result. The screenshot is an editor viewport capture, not a recording or screenshot of the separate running game window.

Godot 4.0 and 4.1 can use the editor control tools. Godot added the editor viewport accessors needed for screenshots in 4.2, so screenshots require 4.2 or newer. The add-on is bundled under godot_plugin/addons/godot_mcp_assistant and is copied into each game project by the install tool.

Connect Codex

Codex CLI and the Codex IDE extension share the MCP configuration. From PowerShell, add this local stdio server with the Codex CLI. Replace the example path with the location of this repository:

codex mcp add godot-mcp-assistant -- node "C:\path\to\godot-mcp-assistant\index.js"
codex mcp list

Restart Codex after adding the server. The tools should then appear in Codex's MCP tool list.

You can also add the server manually to ~/.codex/config.toml (on Windows, usually %USERPROFILE%\.codex\config.toml):

[mcp_servers.godot-mcp-assistant]
command = "node"
args = ["C:\\path\\to\\godot-mcp-assistant\\index.js"]
enabled = true

See OpenAI's Codex MCP setup guide and Codex configuration reference.

Connect Cursor

Add the server to the project-specific .cursor/mcp.json file in the game project, or to Cursor's global MCP configuration. Replace the example path with the location of this repository on your machine.

{
  "mcpServers": {
    "godot-mcp-assistant": {
      "command": "node",
      "args": ["C:\\path\\to\\godot-mcp-assistant\\index.js"]
    }
  }
}

Restart Cursor or reload its MCP servers. Confirm that the Godot tools appear in the available tools list. Cursor documents project-specific configuration in its MCP guide.

Connect Claude Desktop

Install as a Claude Desktop extension

This repository includes an MCP Bundle manifest. From the repository directory, install dependencies and create the extension bundle:

npm install
npm install -g @anthropic-ai/mcpb
mcpb validate manifest.json
mcpb pack . godot-mcp-assistant.mcpb

In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension… and select the generated godot-mcp-assistant.mcpb file. Restart Claude Desktop if it does not appear immediately. The bundle starts the local Node.js server; the AI client supplies the absolute Godot project path in each tool call.

See Anthropic's local MCP server guide and the MCPB manifest specification.

Manual stdio configuration

For clients or Claude Desktop installations that use a manual MCP configuration, add this entry under mcpServers. On Windows, the Claude Desktop configuration file is usually under %APPDATA%\Claude\claude_desktop_config.json. If the client cannot find node, set command to the absolute path of your Node.js executable.

{
  "mcpServers": {
    "godot-mcp-assistant": {
      "command": "node",
      "args": ["C:\\path\\to\\godot-mcp-assistant\\index.js"]
    }
  }
}

Restart the client and check that the server and its tools are available. See Anthropic's MCP documentation for client setup information.

Example request

After connecting the server, ask the assistant something like:

Create a fully functional top-down player for my Godot 4 project at C:\Games\MyGame. Create scripts/player.gd extending CharacterBody2D with movement using Godot's default ui_left, ui_right, ui_up, and ui_down actions. Then create scenes/player.tscn with a CharacterBody2D root, attach that script, and add a Sprite2D and a CollisionShape2D with a capsule shape. Use existing project assets when appropriate, and tell me if an asset path is missing.

The assistant can analyze the project first, create the script, and then generate a scene that references the script and shape resource. For a new visual asset, provide an existing res:// path or ask your assistant to create the asset through another workflow.

Tool inputs

create_gdscript

{
  "projectPath": "C:/Games/MyGame",
  "scriptPath": "scripts/player.gd",
  "baseClass": "CharacterBody2D",
  "content": "extends CharacterBody2D\n\n@export var speed: float = 300.0\n\nfunc _physics_process(_delta: float) -> void:\n    var direction := Input.get_vector(\"ui_left\", \"ui_right\", \"ui_up\", \"ui_down\")\n    velocity = direction * speed\n    move_and_slide()"
}

The content field is optional. Without it, the tool generates a starter script for the selected base class. Supplied source gets an extends line if missing, and a conflicting extends declaration is rejected. Existing files are not overwritten unless overwrite is explicitly set to true.

generate_tscn_scene

Pass a JSON object with a root node, optional external resources, optional sub-resources, and nested children. Node and resource properties use Godot Variant-compatible JSON values. Use $expression only when a property needs a Godot expression such as Vector2(16, 16) or Color(1, 1, 1, 1). Use $extResource and $subResource to reference declared resources.

{
  "projectPath": "C:/Games/MyGame",
  "scenePath": "scenes/player.tscn",
  "scene": {
    "resources": [
      {
        "id": "player_script",
        "type": "Script",
        "path": "res://scripts/player.gd"
      }
    ],
    "subResources": [
      {
        "id": "player_shape",
        "type": "CapsuleShape2D",
        "properties": {
          "radius": 12.0,
          "height": 32.0
        }
      }
    ],
    "root": {
      "name": "Player",
      "type": "CharacterBody2D",
      "properties": {
        "script": {
          "$extResource": "player_script"
        }
      },
      "children": [
        {
          "name": "Sprite2D",
          "type": "Sprite2D"
        },
        {
          "name": "CollisionShape2D",
          "type": "CollisionShape2D",
          "properties": {
            "shape": {
              "$subResource": "player_shape"
            }
          }
        }
      ]
    }
  }
}

Scene files are created with Godot format version 3. External resource paths should use res://. This tool writes the scene text; it does not import or validate referenced assets in the Godot editor.

analyze_project_godot

{
  "projectPath": "C:/Games/MyGame"
}

The response includes a sections object. Each setting retains both its original raw text and a best-effort parsed value. Common packed-array constructors are parsed into arrays. Other Godot-specific constructors that are not simple arrays, dictionaries, strings, numbers, booleans, or null remain available as raw strings.

inject_script_autoload

{
  "projectPath": "C:/Games/MyGame",
  "singletonName": "GameState",
  "scriptPath": "res://scripts/game_state.gd"
}

The GDScript must already exist. If an Autoload with that name points elsewhere, the call returns an error unless replaceExisting is set to true. The tool preserves the other project settings and adds or updates only the named entry in [autoload].

Godot editor bridge tools

Install the optional add-on once for each game project:

{
  "projectPath": "C:/Games/MyGame"
}

Pass that input to install_godot_editor_bridge, then open the project in Godot. The editor must remain open for the bridge tools. For example, call godot_editor_status with the same project path, then use:

{
  "projectPath": "C:/Games/MyGame",
  "scenePath": "scenes/player.tscn"
}

Pass this input to godot_open_scene or godot_play_scene. To capture the editor's current 2D viewport, call capture_godot_viewport with {"projectPath":"C:/Games/MyGame","viewport":"2d"}; use "3d" for the 3D editor viewport. The tool attaches the PNG image to its MCP response. Screenshots require a normally running desktop editor, not --headless. Editor controls support Godot 4.0 and newer; viewport capture requires Godot 4.2 or newer.

File access and safety

• projectPath must be absolute and must contain project.godot.

• Created script and scene paths are relative to the project and cannot escape it.

• Existing files are preserved by default. Set overwrite only when you intentionally want to replace a script or scene.

• The Autoload tool requires an existing script inside the project and only accepts res:// paths.

• The file tools do not execute GDScript. The optional editor bridge launches a scene through the open Godot editor. Review generated changes in version control and use Godot to validate project behavior.

• The editor add-on listens only on loopback and accepts a limited set of bridge commands. Install it only in projects you trust.

MCP tools can read or change files accessible to the configured client process. Connect this server only to AI clients and projects you trust.

Development

npm install
npm start

This project uses the v1 @modelcontextprotocol/sdk package requested for compatibility with clients that support the standard MCP stdio transport. See the SDK v1 documentation and the stdio server guide.

License

MIT