Skip to main content
Glama

godot-assistant

CI npm Godot 4.3+ License: MIT

An MCP server that lets an AI coding agent actually work on a Godot 4 project: read scenes, edit node trees, write and validate GDScript, run the game, and look at what it built.

jmsansan.github.io/godot-assistant

Works with Claude Code, Codex, Cursor, Claude Desktop, Cline, Windsurf, or any MCP client.

claude mcp add godot-assistant -- npx -y godot-assistant --project /path/to/your/game

That is the whole installation. No addon to copy, no build step, no project changes.


Why another Godot MCP

Existing servers land on one of two extremes. One is command-line only: easy to install, but it cannot see the editor, cannot see the running game, and cannot show you a single pixel, so an agent works blind and finds out something is wrong only when it crashes. The other exposes 175 tools through a mandatory editor plugin, which is enough tool definitions to measurably degrade the model doing the work.

godot-assistant takes the middle path deliberately:

Zero-setup by default. Every core capability (reading scenes, editing nodes, writing scripts, validating, running, and rendering a scene to a PNG) runs through the Godot binary you already have. Nothing is written into your project.

Live features when you want them. One call to bridge_install adds a small optional addon that unlocks inspecting the running game, simulating input, and screenshotting the game and editor. Without it, those tools fail with an explanation instead of a stack trace; everything else is unaffected.

25 tools, not 175. Grouped by intent with batched operations, so the model spends its context on your game instead of on tool definitions. The full set costs about 6.5k tokens.

It refuses to corrupt your scenes. See Safety.


Related MCP server: Gear

Quick start

Prerequisites: Godot 4.x (download) and Node.js 18+. Godot is auto-detected on macOS, Windows and Linux, including Homebrew, Scoop, Snap and Flatpak installs.

Claude Code

claude mcp add godot-assistant -- npx -y godot-assistant --project /path/to/your/game

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.godot-assistant]
command = "npx"
args = ["-y", "godot-assistant", "--project", "/path/to/your/game"]

Cursor / Claude Desktop / Cline / Windsurf

In your client's mcp.json:

{
  "mcpServers": {
    "godot-assistant": {
      "command": "npx",
      "args": ["-y", "godot-assistant", "--project", "/path/to/your/game"]
    }
  }
}

--project is optional. Omit it and pass project per tool call instead. Setting it is recommended: it removes an argument from every call.

Check the setup

npx -y godot-assistant doctor --project /path/to/your/game
godot-assistant 1.0.0

node: v22.11.0
godot: 4.7.1.stable.official
  path: /Applications/Godot.app/Contents/MacOS/Godot
  found via: standard install
  C# support: no
project: My Game
  path: /path/to/your/game
  main scene: res://scenes/main.tscn
  language: GDScript
  live bridge: not running (optional)

All checks passed.

npx -y godot-assistant install prints ready-to-paste config for every client.


What you can ask for

"Add a double jump to the player and show me it working."

The agent reads player.gd, checks CharacterBody2D against the real engine API, edits the script, validates it, runs the game, and screenshots the result.

"The coin pickup isn't firing. Why?"

scene_tree on the level, node_inspect on the coin to see its signal wiring, search for the handler, run_project to read the actual error with a file and line number.

"Build a pause menu."

api_reference for Control and Button, scene_create, node_add for the layout in one batch, signal_connect to wire the buttons, screenshot to check it looks right.


Tools

Discovery

Tool

What it does

godot_status

Engine, project, bridge and process health. Start here.

project_info

Main scene, autoloads, input actions, layers, file counts.

list_files

Project files by kind, with glob and paging.

search

Grep scripts, scenes and resources; returns file:line.

Engine API

Tool

What it does

api_reference

Methods, properties, signals and enums from the installed engine's ClassDB.

This one matters more than it looks. Godot's API changed substantially at 4.0 and keeps moving across minors, so a model working from memory invents method names and mixes up signal signatures. api_reference replaces recall with a lookup against the exact engine version in use.

Scenes and nodes

Tool

What it does

scene_tree

Node hierarchy with types, scripts, instances and groups.

scene_create

New .tscn with a chosen root type, assigned a stable uid://.

node_add

Add nodes in a batch, with typed properties.

node_modify

Batch set-properties, rename, delete, reparent, reorder, scripts, groups.

node_inspect

One node in full: non-default properties, both directions of signal wiring.

scene_instance

Place a scene inside another as an instance (Godot's prefabs).

signal_connect

Connect/disconnect signals, persisted exactly as the editor writes them.

Scripting

Tool

What it does

script_create

Write a script and optionally attach it in one step.

script_validate

Parse-check one file or the whole project, with file and line.

Running and debugging

Tool

What it does

run_project

Run the game or one scene, windowed or headless.

get_output

Parsed, deduplicated console output.

stop_project

Stop cleanly.

Seeing

Tool

What it does

screenshot

Render any scene to PNG, no setup needed. Or capture the running game / editor (needs the bridge).

runtime_inspect

Live node tree, world positions and real property values while running. (bridge)

simulate_input

Send actions, keys, clicks into the running game. (bridge)

Assets, editor, export

Tool

What it does

resource_manage

Create, read and edit .tres resources.

import_assets

Find and fix unimported assets.

editor_control

Launch the editor; open scenes, play/stop, select nodes. (bridge)

bridge_install

Install, check or remove the optional live addon.

export_project

List presets and build.


Property values

JSON has no Vector2, so properties are converted for you:

{
  "position":  [100, 250],        // -> Vector2(100, 250)
  "scale":     [2, 2, 2],         // -> Vector3(2, 2, 2)
  "modulate":  "#ff8800",         // -> Color
  "texture":   "res://icon.png",  // -> loaded Resource
  "mouse_filter": "MOUSE_FILTER_IGNORE"  // -> enum constant
}

Anything else passes through with the property's declared type. A name that does not exist on the node is reported rather than silently dropped.


The optional live bridge

bridge_install

Adds addons/godot_assistant/ and enables it. This unlocks:

  • screenshot(source="game") and source="editor"

  • simulate_input: drive the game with synthetic input

  • runtime_inspect: the live tree, including inside instanced scenes

  • editor_control: open scenes, play/stop, read editor state

Security posture. The bridge listens on 127.0.0.1 only, requires a token regenerated every session, and refuses to start in non-debug builds so exported games never carry it. The discovery file lives in .godot/, which Godot already git-ignores. Port assignment is dynamic, so several projects can be open at once.

Remove it any time with bridge_install action="uninstall".


Safety

Scene files are the crown jewels of a Godot project and a bad write is easy to miss for hours. This server is built around not doing that.

It will not silently drop your scripts. Editing a scene means loading, mutating and repacking it. If a script fails to compile, the engine drops the reference and the save would quietly detach it from your node. That write is refused, with the offending script named and the file untouched. force=true is available when the removal is genuinely intended.

It will not break your uid://. Repacking a scene loses the UID in its header, which breaks every other scene referencing it. The UID is captured before the edit and restored after.

It will not corrupt C# scenes. A non-.NET Godot build cannot resolve CSharpScript, so editing a scene with C# attached strips those attachments. Detected up front and refused, with instructions.

It will not run code you did not ask for. Node types are validated as bare identifiers and checked against ClassDB on both sides, so a res://payload.gd passed as a node type is rejected rather than loaded and executed.

It will not escape your project. Paths are normalised, NUL-checked, and resolved through realpath before the containment check, so symlinks cannot step outside the project root.

It will not hang. Every engine invocation has a hard timeout and a kill escalation. (A headless Godot waiting on a rendered frame waits forever: a real thing this server works around.)

Read-only mode. --read-only (or GODOT_ASSISTANT_READ_ONLY=1) refuses every mutating tool while leaving inspection intact.


Token efficiency

MCP responses are billed to the agent's context, so:

  • Plain text, not JSON. A scene tree of 8 nodes is ~420 characters, roughly a third of the equivalent JSON.

  • Defaults elided. node_inspect shows only properties that differ from engine defaults.

  • Duplicates collapsed. An error thrown every frame appears once, with a count.

  • Engine noise filtered. Leaked-RID warnings at shutdown are normal and are removed; agents otherwise chase them.

  • Everything paginates, with an explicit offset= hint to resume.

  • 25 tools with compact schemas, about 6.5k tokens for the full set.


Configuration

Setting

Env

Flag

Godot executable

GODOT_PATH

--godot <path>

Default project

GODOT_ASSISTANT_PROJECT

--project <path>

Read-only

GODOT_ASSISTANT_READ_ONLY=1

--read-only

Commands: godot-assistant (serve), doctor, install, --help, --version.


Troubleshooting

"Could not find a Godot executable." Set GODOT_PATH in the MCP config's env block. On macOS point at the binary inside the bundle, not the .app folder:

"env": { "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot" }

"No project.godot found." Point --project at the folder containing project.godot. Any path inside the project also works, because it walks up.

"Godot did not return a result." Usually a script in the project fails to parse. Run script_validate.

Screenshots time out or look stale. The game window must be visible to render; run_project sets always-on-top by default for this reason. On a headless server with no display, scene rendering is unavailable, so use headless=true runs and read the console instead.

C# project. Install the .NET build of Godot and point GODOT_PATH at it. Scene edits touching C# are refused with a standard build rather than silently corrupting the file.


Development

npm install
npm run build
npm test          # end-to-end suite against a real Godot binary

The QA suite builds a throwaway project with instanced scenes, sub-resources, exported overrides and signal connections, then drives the server over real MCP stdio: 109 checks covering protocol shape, scene-edit fidelity, path-traversal and code-execution rejection, live-bridge behaviour, graceful degradation, error quality and output size.


License

MIT


Support

If this saves you time, you can support the work on GitHub Sponsors or Ko-fi.

Available Tools

25 tools
api_referenceGodot API referenceA

Look up a Godot class in the installed engine: methods with full signatures, properties with defaults, signals, enums, inheritance. Use this instead of recalling the API — it reflects the exact engine version in use.

Inputs: query (required), kind, limit, offset, +2 more.

bridge_installInstall live bridge addonA

Install (or remove) the optional Godot addon that enables live features: inspecting the running game, simulating input, screenshotting the game and editor, and driving play/stop. Everything else works without it. Adds files under addons/godot_assistant and enables the plugin.

Inputs: action, project.

editor_controlControl the Godot editorA

Drive a running Godot editor: read what is open, open a scene, save, play/stop, select nodes, rescan the filesystem. Also launches the editor. Most actions need bridge_install.

Inputs: action (required), node, scene, project.

export_projectExport projectB

List export presets, or build one. Presets must first be created in the Godot editor under Project > Export.

Inputs: debug, action, output, preset, +1 more.

get_outputGet run outputA

Read console output from the running (or last) session. Errors and warnings are parsed, deduplicated and shown with file:line; repeated per-frame errors are collapsed.

Inputs: clear, limit, offset, project, +1 more.

godot_statusGodot statusA

Environment and project health check: Godot version, project detection, live bridge state, running processes. Start here when anything is unexpected, or to confirm setup.

Inputs: project.

import_assetsImport assetsA

Find and fix assets Godot has not imported yet. New image or audio files are unusable until imported — that is the cause of "No loader found for resource". Call this after adding files outside the editor.

Inputs: limit, action, offset, project.

list_filesList project filesA

List project files by kind (scenes, scripts, resources, images, audio, models) with optional glob. Use to orient in an unfamiliar project.

Inputs: dir, kind, limit, offset, +2 more.

node_addAdd nodes to sceneA

Add one or more nodes to a scene in a single save. Batch related nodes together — each call reloads and rewrites the scene file.

Inputs: nodes (required), scene (required), force, project.

node_inspectInspect nodeA

Full detail for one node: type, inheritance chain, script, groups, signal connections, and properties that differ from their defaults.

Inputs: scene (required), node, project, include_defaults.

node_modifyModify nodesA

Apply a batch of edits to a scene: set properties, rename, delete, reparent, reorder, attach/detach scripts, manage groups. All operations are applied then saved once.

Inputs: scene (required), operations (required), force, project.

project_infoProject infoA

Project settings that matter for writing code: main scene, autoload singletons, input actions, physics layers, file counts. Read this before generating gameplay code.

Inputs: include, project.

resource_manageManage resourcesA

Create, read or edit Godot resource files (.tres): materials, themes, curves, tilesets, physics shapes, input/animation data. Use api_reference first to find the right class and property names.

Inputs: path (required), action (required), type, project, +2 more.

run_projectRun projectA

Launch the game and capture its output. Runs the main scene, or one specific scene. Use wait_seconds for a quick check that returns the log; omit it to leave the game running and poll with get_output.

Inputs: args, scene, project, replace, +3 more.

runtime_inspectInspect running gameA

Read the live state of the running game: actual node tree with world positions and visibility, real property values, FPS and node counts. Shows what is true at runtime, which often differs from the scene file. Requires bridge_install.

Inputs: node, what, project, max_depth, +1 more.

scene_createCreate sceneA

Create a new .tscn with a chosen root node type, optionally attaching a script. Assigns a stable uid:// so other scenes can reference it.

Inputs: scene (required), script, project, overwrite, +2 more.

scene_instanceInstance a sceneA

Place one scene inside another as an instance (not a copy), so later edits to the source propagate. This is how prefabs work in Godot.

Inputs: scene (required), instance (required), name, count, +4 more.

scene_treeRead scene treeA

Show a scene's node hierarchy with types, attached scripts, instanced sub-scenes and groups. Read this before editing any scene.

Inputs: scene (required), project, max_depth.

screenshotScreenshotA

See what a scene actually looks like. scene renders any scene offscreen with no setup. game captures the running game and editor captures the Godot editor (both need bridge_install). Use this to verify layout and visuals — the console cannot show them.

Inputs: scene, width, frames, height, +3 more.

script_createCreate scriptA

Write a new GDScript file, optionally attaching it to a node in a scene in the same step. Provide content for real code; omit it for a stub.

Inputs: path (required), content, extends, project, +4 more.

script_validateValidate scriptsA

Parse-check GDScript — one file or the whole project — and report errors with file and line. Run this after editing scripts and before running the game; it is much faster than launching.

Inputs: path, project.

signal_connectConnect signalsA

Connect or disconnect a signal between nodes in a scene, persisted into the .tscn exactly as the editor writes it. The receiving method must exist on the target's script.

Inputs: scene (required), method (required), signal (required), to, +6 more.

simulate_inputSimulate inputA

Send synthetic input to the running game — a mapped action, a key, a mouse move or a click. Goes through Godot's input system, so the game reacts exactly as it would to a real device. Requires bridge_install and a running game.

Inputs: kind (required), x, y, alt, +8 more.

stop_projectStop projectB

Stop the running game or editor started by this server, and return the final output summary.

Inputs: what, project.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 25 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes (e.g., script_create vs. resource_manage, node_add vs. node_modify, scene_tree vs. node_inspect). Some overlap exists between run_project and editor_control's play/stop, and between get_output and stop_project, but descriptions clarify the boundaries.

    Naming Consistency4/5

    Tool names follow a mostly readable noun_verb or verb_noun pattern with underscores. Groups like scene_* and node_* are consistently prefixed, though overall conventions vary (e.g., stop_project vs. project_info, import_assets vs. resource_manage).

    Tool Count3/5

    25 tools is on the heavy side, near the upper limit of the borderline range. The count is justified by Godot's complexity, but some tools could potentially be consolidated (e.g., node_add and node_modify, or run_project and editor_control).

    Completeness4/5

    The tool set covers project info, file/file management, scripting, resources, scenes, nodes, signals, running/debugging, editor control, and export. Minor gaps include no scene deletion tool and no project settings modification, but core workflows are well supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives AI assistants direct control over Godot 4 game development projects. It enables launching the editor, running projects, creating and editing scenes, writing GDScript, and inspecting assets through natural language commands.
      44
      14 npm
      4
      MIT
    • 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