godot-assistant

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.

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.