godot-assistant
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@godot-assistant Add a double jump to the player and show me it working."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/gameThat 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/gameCodex 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/gamegodot-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 |
| Engine, project, bridge and process health. Start here. |
| Main scene, autoloads, input actions, layers, file counts. |
| Project files by kind, with glob and paging. |
| Grep scripts, scenes and resources; returns |
Engine API
Tool | What it does |
| 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 |
| Node hierarchy with types, scripts, instances and groups. |
| New |
| Add nodes in a batch, with typed properties. |
| Batch set-properties, rename, delete, reparent, reorder, scripts, groups. |
| One node in full: non-default properties, both directions of signal wiring. |
| Place a scene inside another as an instance (Godot's prefabs). |
| Connect/disconnect signals, persisted exactly as the editor writes them. |
Scripting
Tool | What it does |
| Write a script and optionally attach it in one step. |
| Parse-check one file or the whole project, with file and line. |
Running and debugging
Tool | What it does |
| Run the game or one scene, windowed or headless. |
| Parsed, deduplicated console output. |
| Stop cleanly. |
Seeing
Tool | What it does |
| Render any scene to PNG, no setup needed. Or capture the running game / editor (needs the bridge). |
| Live node tree, world positions and real property values while running. (bridge) |
| Send actions, keys, clicks into the running game. (bridge) |
Assets, editor, export
Tool | What it does |
| Create, read and edit |
| Find and fix unimported assets. |
| Launch the editor; open scenes, play/stop, select nodes. (bridge) |
| Install, check or remove the optional live addon. |
| 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_installAdds addons/godot_assistant/ and enables it. This unlocks:
screenshot(source="game")andsource="editor"simulate_input: drive the game with synthetic inputruntime_inspect: the live tree, including inside instanced sceneseditor_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_inspectshows 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 |
|
|
Default project |
|
|
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 binaryThe 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 toolsapi_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.
searchSearch projectA
Grep across scripts, scenes and resources. Finds symbol definitions, node types used in scenes, signal names, TODOs. Returns file:line with the matching line.
Inputs: query (required), kind, limit, offset, +2 more.
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
Scored across 25 tools
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.
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).
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).
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
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
An MCP server that gives your AI access to the source code and docs of all public github repos
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.4414 npm4MIT
- AlicenseAqualityDmaintenanceAn 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.333MIT
- AlicenseBqualityDmaintenanceAn 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.16MIT
- AlicenseAqualityDmaintenanceAn 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.75187 npm8MIT