godot-mcp
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-mcp Add a Coin Area2D at (400, 260) to scenes/Main.tscn"
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-mcp
An MCP server that lets Claude (or any MCP
client) work on Godot 4 projects: it edits .tscn scenes and .gd scripts
directly on disk, runs the project headlessly to catch errors, and can
optionally drive a running Godot editor over a local WebSocket bridge.
File tools edit scenes and scripts on disk. They need no Godot install and no setup beyond building the server.
Live-editor tools need the small companion plugin enabled in an open editor. They let Claude edit the open scene inside the editor — you watch each node appear, and Ctrl+Z undoes it — and play/stop scenes.

New to Godot? Click the picture for a 23-second look at how godot-mcp works today.
godot-mcp/
├── src/ # the MCP server (TypeScript)
│ ├── index.ts # tool definitions
│ ├── tscn.ts # .tscn parser/serializer (no Godot needed to use it)
│ └── bridge.ts # WebSocket client for the live editor bridge
├── sample-project/ # a working Godot 4 project to try the tools on
│ ├── scenes/Main.tscn
│ ├── scripts/ # player.gd (the ball), camera_rig.gd, game.gd
│ └── addons/godot_mcp_bridge/ # the live-bridge EditorPlugin
└── test/ # `npm test`The sample project is a small 3D game: roll a ball (WASD or arrow keys, Space to jump, mouse or Q/E to orbit the third-person camera) over ramps, past boxes and crates, to the glowing goal pad. R restarts.
Contents
Related MCP server: Godot MCP Flash
Quick start
Requires Node.js 18+. No install step: your MCP client runs the published
package through npx.
Claude Code
claude mcp add godot -- npx -y @yasirurf/godot-mcpOr add it by hand to a project's .mcp.json:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@yasirurf/godot-mcp"]
}
}
}Claude Desktop — add the same mcpServers entry to
claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/,
Windows: %APPDATA%\Claude\), then restart the app.
git clone https://github.com/YasiruRF/godot-mcp.git
cd godot-mcp
npm install
npm run buildRegister the built server using the absolute path to dist/index.js:
claude mcp add godot -- node /absolute/path/to/godot-mcp/dist/index.jsOn Windows use a Windows path, e.g. node C:\dev\godot-mcp\dist\index.js, and
escape the backslashes in JSON: "C:\\dev\\godot-mcp\\dist\\index.js".
Then ask Claude something like "List everything in the Godot project at
/path/to/my-game". If it returns your scenes and scripts, you're set.
Usage guide
1. Point the tools at a project
Every file tool takes a project_path: the absolute path to the folder that
contains project.godot. Tools refuse to run if that file isn't there, and
they refuse to read or write anything outside the folder.
Other paths (scene_path, script_path, ...) can be given relative to the
project (scenes/Main.tscn), as res:// paths (res://scenes/Main.tscn), or
as absolute paths inside the project. Tip for your prompts: tell Claude the
project path once ("my project is at D:\games\platformer") and it will reuse it.
To try things out without risking your own work, use the bundled
sample-project/ (or a copy of it).
2. Build and edit scenes
Scenes are addressed by node path: . is the scene root, Player is a
child of the root, Player/Ball is a child of Player.
Example conversation:
You: In
scenes/Main.tscn, add anArea3DcalledCoinunder the root with aCollisionShape3Dchild, and put the coin at (2, 1, -10).
Claude will call, in order:
Call | Arguments |
|
|
|
|
|
|
Property values are raw Godot text, exactly as they appear in a .tscn
file: Vector2(10, 20), Color(1, 0, 0, 1), false, "a string" (with the
quotes), ExtResource("1_abcde"). They are not validated, so a wrong value is
only caught when Godot loads the scene — use run_headless (below) after edits.
To attach a script when adding a node, pass script_path
("script_path": "scripts/coin.gd"). The server registers the script in the
scene for you.
To start a scene from scratch, use create_scene first (it won't overwrite an
existing file unless you pass overwrite: true), then add_node.
Editor open? Godot keeps its own in-memory copy of an open scene, so editing the file on disk underneath it makes the two diverge (and whichever is saved last wins). When the bridge plugin is running, these on-disk tools therefore refuse to edit a scene that is open in the editor and point you to the live-editing tools (or to closing the scene's tab first). Without the plugin they can't tell, so save and close the scene in Godot before asking Claude to edit it on disk.
3. Read and edit scripts
read_scriptreturns a.gdfile.write_scriptcreates or fully overwrites a file.edit_scriptis a targeted find-and-replace:old_textmust match exactly once, otherwise the call fails and nothing is changed (so include enough surrounding lines to make it unique).
You: Open
scripts/player.gdand add a double-jump.
4. Check that it actually works: run_headless
run_headless launches Godot with --headless on your project (or one scene),
lets it run for timeout_ms (default 5000), and returns everything it printed,
followed by an exit status line such as [exit code 0] or
[stopped by SIGTERM after the 5000ms timeout]. Parse errors, missing
resources and runtime errors show up in the output, which makes it a good
follow-up to any edit: "Make that change, then run the project headlessly and
tell me if there are errors."
It needs a Godot 4 executable. If it isn't on your PATH as godot4, set
GODOT_BIN (see Configuration).
5. Live editing: watch Claude work in the editor
With the bridge plugin enabled, Claude can edit the scene inside the running
Godot editor instead of on disk. Each edit appears immediately in the Scene
dock and the viewport, the affected node is selected, and every edit is a step
in Godot's undo history — press Ctrl+Z to take it back. Nothing is written
to disk until the scene is saved (Ctrl+S, or Claude's editor_save_scene).
Set up the plugin (once per project)
Copy
sample-project/addons/godot_mcp_bridge/into your project'saddons/folder (or just opensample-project/in Godot, where it's already enabled).In Godot: Project → Project Settings → Plugins → enable "Godot MCP Bridge".
The Output panel should print
godot_mcp_bridge: listening on ws://127.0.0.1:9080.Ask Claude to
editor_ping. A reply like{"status": "alive", ...}means the bridge is up.
After updating the server, also refresh the plugin copy in your project and toggle it off and on (or reopen the project) so Godot loads the new version.
A live session
You: Open
scenes/Main.tscnin the editor and add a crate: aStaticBody3Dat (3, 1, -20) with a 2×2×2 box collision shape and a brown box mesh as its visual.
Claude calls, and you watch the nodes appear one by one:
Call | Arguments |
|
|
|
|
|
|
|
|
Not happy with it? Ctrl+Z. Happy? Save with Ctrl+S, or ask "save it"
(editor_save_scene). Then "run it" (editor_run_scene) to play the scene.
Claude can also read what's open (editor_get_scene_tree) and what you have
selected (editor_get_selection — "which node do I have selected?").
Property values use Godot syntax: Vector2(1, 2), Color(1, 0, 0, 1) (all
four components), true, 42, and text with its quotes
("\"Hello\""). For a resource property such as a collision shape,
ClassName.new() creates a fresh resource and "shape:size" sets a property
inside it (properties are applied in order, so set shape first). If any value
in a call is invalid, the whole call is rejected and nothing is changed.
Live edits act on the scene in the editor's active tab — use
editor_open_scene to switch. They work on nodes that belong to that scene
(not the internals of instanced sub-scenes).
The bridge is tested against Godot 4.7.2; it needs the EditorInterface
singleton and WebSocketPeer.accept_stream, so Godot 4.2 or newer is the
likely minimum. The sample project targets 4.3.
Tool reference
File tools (always available)
Tool | Arguments | Purpose |
|
| Lists scenes ( |
|
| Parses a |
|
| Creates a new scene with one root node |
|
| Adds a child node (use |
|
| Removes a node, its descendants, and any signal connections pointing at them. The root can't be removed |
|
| Sets or overwrites raw properties on a node |
|
| Creates or overwrites a script |
|
| Reads a script |
|
| Replaces exactly one occurrence of |
|
| Runs the project headlessly and returns its output and exit status |
Node names may not contain . / : @ " % or backslashes, and node types must be
plain class names such as Sprite2D (both are Godot rules).
Live editor bridge (needs the plugin enabled in a running editor)
Tool | Arguments | Purpose |
| — | Checks the bridge is reachable (returns the Godot version) |
| — | Returns the scene open in the editor as a node tree, plus the list of open scenes |
|
| Opens a scene in the editor (switches to its tab) |
|
| Adds a node to the open scene — live, selected, undoable |
|
| Sets properties on a node in the open scene — live, undoable |
|
| Removes a node and its descendants from the open scene — live, undoable |
| — | Saves the open scene to disk (like Ctrl+S) |
|
| Presses "Play Scene" on that scene |
| — | Stops the running scene |
| — | Returns the node path(s) currently selected in the editor |
scene_path on the live-edit tools is an optional safety check: the call fails
unless that is the scene currently open. Values use Godot syntax (see
Live editing).
Configuration
Variable | Default | Meaning |
|
| Godot 4 executable used by |
|
| Where the |
Set them in your MCP client config, for example:
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@yasirurf/godot-mcp"],
"env": { "GODOT_BIN": "C:\\Godot\\Godot_v4.3-stable_win64_console.exe" }
}
}
}On Windows, prefer the _console.exe build of Godot for run_headless — it
attaches stdout/stderr so errors show up in the output.
The bridge's port is fixed at 9080 in
sample-project/addons/godot_mcp_bridge/godot_mcp_bridge.gd (PORT); if you
change it there, change GODOT_MCP_BRIDGE_URL to match.
Troubleshooting
Symptom | Cause / fix |
|
|
| A |
| Godot isn't on |
| Use the |
| Godot isn't open, or the plugin isn't enabled (Project Settings → Plugins). File tools still work without it |
Plugin logs | Another Godot editor (or program) already holds the port — close it |
| Add more surrounding lines to |
Edits don't show in the open editor | Godot caches open scenes; accept its "reload from disk" prompt |
| Deliberate guard. Use |
| Live edits act on the editor's active tab. Call |
| Use Godot syntax: |
|
|
| Your project has an older copy of the plugin. Re-copy |
Claude can't see the tools | Check the path in your MCP config is absolute and points at |
How it works
Godot doesn't expose an API for external processes to control it, so the project splits into two independent halves:
File-based tools.
.tscnand.gdfiles are plain text. The server parses and writes them directly, so these tools work with zero Godot-side setup — you don't even need Godot installed, except forrun_headless. The.tscnhandling is conservative: it edits the blocks it needs and keeps everything else in the file verbatim, so an edit produces a small diff and an untouched scene round-trips byte for byte.Live editor bridge. A small
EditorPlugin(sample-project/addons/godot_mcp_bridge/) runs inside the Godot editor and opensws://127.0.0.1:9080. Theeditor_*tools connect to it, send one JSON command ({"id", "command", "args"}) and read one JSON reply ({"id", "ok", "result", "error"}). Scene edits go through the editor'sEditorUndoRedoManageron the scene that is actually open, which is why they show up live and can be undone. The on-disk tools ask the bridge whether a scene is open before touching its file, and refuse if it is.
Known limitations
The
.tscnparser handles nodes, ext/sub resources and single-line properties. Properties whose values span several lines (some dictionaries and arrays) are preserved when untouched, butread_sceneonly shows their first line andset_node_propertiescan't replace them reliably. Do those edits in the Godot editor.Property values and node types are not validated against Godot's class database — run
run_headlessafter edits.run_headlessand the live bridge need a local Godot install; the other tools don't.The live bridge has no authentication. It binds to
127.0.0.1only, but any local program — and potentially a web page in your browser, since browsers allow WebSocket connections to localhost — can send it commands while the plugin is enabled. Those commands can change (undoably) and save the open scene. Enable the plugin while you use it, and never expose the port on a shared or public host.Live edits act on the scene in the active editor tab, on nodes that belong to it (not the internals of instanced sub-scenes). There is no MCP-side undo; use Ctrl+Z in the editor.
Tested against Godot 4.7.2: the bridge plugin was run end to end in a real (headless) Godot editor, and
run_headlesswith the real binary. Those runs are manual, not part ofnpm test, which uses stand-ins (a mock WebSocket server and a fake binary). Older Godot 4 versions are untested.
Development
npm install
npm test # builds, then runs the test suite (no Godot required)
npm run dev # tsc in watch modeThe tests cover the .tscn round-trip and edit operations, drive the built
server over the real MCP stdio protocol against a scratch copy of
sample-project/, and check the bridge client against a mock of the plugin's
WebSocket protocol.
Ideas for later: instance_scene (instance one .tscn in another),
editor_call_method, signal connection editing, export-preset management.
Available Tools
20 toolsadd_nodeB
Adds a child node to an existing scene at the given parent path (use "." for the scene root).
Inputs: name (required), type (required), scene_path (required), parent_path (required), +3 more.
create_sceneB
Creates a new .tscn file with a single root node. Use add_node afterward to build out the tree.
Inputs: root_name (required), root_type (required), scene_path (required), project_path (required), +1 more.
editor_add_nodeA
Adds a node to the scene open in the Godot editor. It appears live and is selected; undo with Ctrl+Z. The scene is not saved until editor_save_scene (or the user saves). Prefer this over add_node while the editor is open.
Inputs: name (required), type (required), parent_path (required), properties, +2 more.
editor_get_scene_treeA
Returns the scene currently open in the Godot editor as a node tree, plus the list of open scenes.
Inputs: no named parameters.
editor_get_selectionA
Returns the currently selected node(s) in the Godot editor.
Inputs: no named parameters.
editor_open_sceneA
Opens a scene in the Godot editor (switching to its tab) so it can be edited live with editor_add_node, editor_set_properties and editor_remove_node.
Inputs: scene_path (required).
editor_pingB
Checks whether the Godot editor is running with the godot_mcp_bridge plugin enabled.
Inputs: no named parameters.
editor_remove_nodeA
Removes a node (and its descendants) from the scene open in the Godot editor (live, undoable with Ctrl+Z).
Inputs: node_path (required), scene_path.
editor_run_sceneA
Tells the running Godot editor to play a specific scene (like pressing the Play Scene button).
Inputs: scene_path (required).
editor_save_sceneA
Saves the scene currently open in the Godot editor to disk (like Ctrl+S).
Inputs: no named parameters.
editor_set_propertiesA
Sets properties on a node in the scene open in the Godot editor (live, undoable with Ctrl+Z, not saved until editor_save_scene).
Inputs: node_path (required), properties (required), scene_path.
editor_stopA
Tells the running Godot editor to stop the currently playing scene.
Inputs: no named parameters.
edit_scriptB
Replaces one exact occurrence of old_text with new_text in a GDScript file (like a find-and-replace patch).
Inputs: new_text (required), old_text (required), script_path (required), project_path (required).
list_projectA
Lists scenes (.tscn), scripts (.gd), and resources (.tres/.res) in a Godot project folder, relative to project_path.
Inputs: project_path (required).
read_sceneB
Parses a .tscn file and returns its node tree as JSON (name, type, parent path, properties).
Inputs: scene_path (required), project_path (required).
read_scriptB
Reads a GDScript (.gd) file's contents.
Inputs: script_path (required), project_path (required).
remove_nodeB
Removes a node (and its descendants) from a scene.
Inputs: node_path (required), scene_path (required), project_path (required).
run_headlessB
Runs the Godot project headlessly (no window) for a fixed duration to catch parse/runtime errors, or runs a specific scene headlessly. Requires the godot4 binary (or GODOT_BIN env var) to be installed.
Inputs: project_path (required), scene_path, timeout_ms.
set_node_propertiesC
Sets or overwrites one or more properties on an existing node in a scene.
Inputs: node_path (required), properties (required), scene_path (required), project_path (required).
write_scriptB
Creates or fully overwrites a GDScript (.gd) file.
Inputs: content (required), script_path (required), project_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
File-based and editor-prefixed tools form two clearly separated groups, and parallel operations like add_node vs editor_add_node are distinguished by both naming and explicit live/undo behavior. Even similar returns like read_scene and editor_get_scene_tree are unambiguous because their sources (disk vs open editor tab) are clearly stated.
Most tools follow a consistent verb_noun or editor_verb_noun pattern, and the editor_ prefix is applied uniformly across live-editor operations. Minor inconsistencies exist in retrieval verbs (list/read/get) and in set_node_properties vs editor_set_properties, but the overall pattern remains predictable.
With 20 tools, the set sits at the heavy end of the range, largely because file-based operations and live-editor operations duplicate each other. Each tool does have a distinct purpose, but the count feels borderline for a single MCP server.
The toolset covers the core Godot workflow well: listing/reading/creating scenes, editing nodes and scripts, headless runs, and live editor control. Minor gaps such as deleting scene files, moving nodes, or deleting/renaming scripts are workable around rather than blocking.
Maintenance
Related MCP Connectors
Drive a live Cinevva game session: edit game files, import CC0 assets, preview changes.
Let your coding agent read your GameSalad projects, and edit them live in Creator on Pro and Edu.
Project management shared by people and AI agents, with persistent project state through MCP.
Project management MCP for AI agents with safe task reads and writes.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables AI assistants to interact with the Godot Engine editor and projects, including scene editing, script management, physics queries, and asset operations.1261MIT
- AlicenseBqualityCmaintenanceEnables AI agents to inspect, modify, run, and debug Godot projects, including scene and script analysis, editor and project management, and visual verification through screenshots.2219 npm14MIT
- AlicenseAqualityBmaintenanceEnables AI agents to read and edit Godot 4.x scenes and resources, introspect the class API, run the game in a managed headless process with frame stepping, input injection and screenshots, validate scripts, and diagnose code via a built-in GDScript LSP plus a bridge to an already open editor.23MIT
- AlicenseNot gradedqualityBmaintenanceEnables compatible AI clients to query and edit game projects through native editor APIs, covering scenes, nodes, components, properties, assets, prefabs, preview, logs, and builds.1MIT