Godot MCP
Provides AI assistants with full control over the Godot game engine, enabling natural language commands to build scenes, write scripts, run games, send input, capture screenshots, and query game state.
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 create a simple platformer level with a player and ground"
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
Give your AI assistant full control over the Godot game engine.
Build scenes, write scripts, run games, send input, capture screenshots, and query live game state — all through natural language.
((((((( (((((((
((((((((((( (((((((((((
((((((((((((( (((((((((((((
(((((((((((((((((((((((((((((((((
((((( ((((((((((((((((((((((((((((((((((((((((( (((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((@@@@@@@(((((((((((((((((((((((((@@@@@@@@((((((((((
((((((@@@@,,,,,@@@((((((((((((((((((((@@@,,,,,@@@@(((((((((
(((((@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((
((((((@@,,,,,,,@@(((((((@@@@@((((((((@@,,,,,,,@@@(((((((((
(((((((((@@@@@@(((((((((@@@@@(((((((((((@@@@@@((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((
@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@
(((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ ((((((((
((((((((( @@(((((((((@@@(((((((((((@@@((((((((((@@ (((((((((
((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@((((((((((
((((((((((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((((((((((((((((((
(((((((((((((((((((((((((((((((((
G O D O T x M O D E L C O N T E X T P R O T O C O LFork of Coding-Solo/godot-mcp, extended with interactive game control, persistent TCP communication, script authoring, automated tests, and more.
Highlights
75 tools covering the full game-dev loop: projects, scenes, nodes, scripts, resources, tilemaps, animation, settings, exports
Interactive play-testing — run the game, send keyboard/mouse/gamepad input, query live state, wait for signals, capture the viewport
Batched test sequences — keys, waits, screenshots, state snapshots, and signal collection in a single round-trip
Stateless MCP
2026-07-28on SDK v2 — no handshake for modern clients, cached tool lists, automatic fallback for 2025-era clientsSafety controls — toolset filtering, read-only mode, and per-tool exclusion via environment variables
Fully tested — 184 automated tests against a real headless Godot engine, no mocks
Related MCP server: Gear
How It Works
MCP (Model Context Protocol) is a standard that lets AI assistants use external tools. Think of it like a USB port — your AI plugs into this server and gains the ability to control Godot.
You (natural language) --> AI Assistant --> MCP Server --> Godot Engine
"Add a player to | | |
the scene" interprets calls tool creates node
your request add_node() in .tscn fileYou talk to your AI assistant normally. When it needs to do something in Godot, it calls one of the 75 tools this server provides. You don't write any code yourself — the AI handles that.
Quickstart
1. Install prerequisites
Requirement | Notes |
Note the full path to the executable (e.g. | |
Runs the MCP server | |
pnpm |
|
An MCP-compatible AI assistant |
2. Clone and build
git clone https://github.com/Vollkorn-Games/godot-mcp.git
cd godot-mcp
pnpm install
pnpm run buildNote the full path to build/index.js — you'll need it below.
3. Configure your AI assistant
Every config needs the same two things: the command to start the server (node + path to build/index.js) and the GODOT_PATH environment variable pointing at your Godot executable.
Run this command in your terminal:
claude mcp add godot -- node /absolute/path/to/godot-mcp/build/index.jsOr add to your MCP settings JSON (~/.claude/settings.json or project-level .mcp.json):
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/absolute/path/to/godot-mcp/build/index.js"],
"env": {
"GODOT_PATH": "/absolute/path/to/godot/executable"
}
}
}
}Open the Cline MCP settings (Cline sidebar > MCP Servers > Configure) and add:
{
"mcpServers": {
"godot": {
"command": "node",
"args": ["/absolute/path/to/godot-mcp/build/index.js"],
"env": {
"GODOT_PATH": "/absolute/path/to/godot/executable"
},
"disabled": false
}
}
}Go to Settings > Features > MCP > + Add New MCP Server:
Name:
godotType:
commandCommand:
node /absolute/path/to/godot-mcp/build/index.js
Then set the environment variable GODOT_PATH in your system or shell profile.
Any application that supports MCP can use this server. The connection always works the same way:
Transport: stdio (the AI launches the server as a subprocess)
Command:
node /absolute/path/to/godot-mcp/build/index.jsEnvironment variables:
GODOT_PATH=/absolute/path/to/godot/executable
Check your client's documentation for where to add MCP server configs. Look for terms like "MCP", "tools", or "tool servers".
On Windows, use forward slashes in JSON paths:"C:/Users/you/godot-mcp/build/index.js".
4. Test it
Open your AI assistant and try:
"Use the get_godot_version tool to check if the MCP server is connected."
If it returns a version number, everything is working. Now try:
"Create a new Godot project at C:/Users/you/my-game with a Node2D main scene."
Tools
This isn't just "launch editor and read logs". The server can build an entire game from scratch — create scenes, add and configure nodes, write GDScript files, wire up signals, set up tilemaps — then run the game, play it via input commands, and observe the results through screenshots and state queries.
75 tools across 10 categories:
Tool | Description |
| Open the Godot editor for a project |
| Run a project in debug mode |
| Get console output/errors (supports filtering) |
| Stop a running project |
| Get installed Godot version |
| Find Godot projects in a directory |
| Analyze project structure |
Tool | Description |
| Create a new scene with a root node type |
| Add nodes with properties |
| Remove nodes from scenes |
| Rename a node in a scene |
| Move a node to a different parent |
| Duplicate a node (optionally to new parent) |
| Add a scene as a child instance |
| Set properties on nodes |
| Read node properties as JSON |
| Get full scene tree structure as JSON |
| Wire signals between nodes |
| Manage node groups |
| Save scene (or create variant) |
| Check for missing scripts, broken refs, etc. |
| Execute multiple scene operations in one Godot process (much faster) |
Tool | Description |
| Write or update a GDScript file (auto-creates directories) |
| Read GDScript file contents |
| Check a GDScript file for syntax errors (headless, no runtime needed) |
| Attach a script to a node in a scene |
Tool | Description |
| Load a texture into a Sprite2D node |
| Create .tres resource files with typed properties |
| Create TileSet with atlas sources and custom data layers |
| Place tiles on a TileMapLayer |
| Read tile data from a TileMapLayer |
| Set custom data on tile cells |
| Export 3D scenes as MeshLibrary for GridMap |
Tool | Description |
| Create AnimationPlayer with pre-configured animations |
| Add animations with tracks, keyframes, interpolation |
| Set collision layers/masks (layer numbers or bitmask) |
Tool | Description |
| Edit project.godot (display, input, etc.) |
| Add, remove, or list autoload singletons |
| Discover all input actions defined in a project |
| UID management (Godot 4.4+) |
| Export for target platform using presets |
Tool | Description |
| Start game with injected TCP input receiver |
| Send named input actions to the running game (move, jump, attack...) |
| Send keyboard key events with modifier support (shift, ctrl, alt) |
| Send mouse clicks at specific viewport coordinates |
| Simulate mouse drag operations from point A to B |
| Query live game state (HP, score, position, level, etc.) |
| Invoke a method on a live node (e.g., |
| Search the runtime scene tree by name pattern and/or type |
| Execute arbitrary GDScript expression at runtime and return result |
| Block until a signal is emitted (e.g., |
| Block until a node appears in the scene tree |
| Retrieve FPS, draw calls, memory, node count, physics stats |
| Reload the current scene (handy for test loops) |
| Retrieve runtime errors/warnings with backtraces (Godot 4.5+ Logger API) |
| Send key presses and InputMap actions with inline waits, screenshots, state snapshots, and signal events |
| Send gamepad button events (A, B, X, Y, shoulders, dpad, start, etc.) |
| Send gamepad analog stick/trigger axis events with float precision |
| Pause/unpause game time (MCP receiver stays active for queries) |
| Set a property on a live node (auto-converts arrays to Vector2/Vector3/Color) |
| Run multi-line GDScript code blocks at runtime with autoload access |
| Subscribe to node signals for async event monitoring |
| Retrieve buffered signal events captured since last read |
| Capture the live game viewport as PNG |
| Run game for N seconds, capture screenshot, stop |
| Render a scene to PNG (static, no runtime) |
Tool | Description |
| Analyze scene architecture: node types, signals, sub-scenes, groups, depth |
| Profile a script: methods, signals, dependencies, exports |
Tool | Description |
| Run GUT unit tests headlessly and return pass/fail results |
Tool | Description |
| Search the Godot Asset Library for addons/templates (read-only network call) |
| Download an asset (by |
Interactive Mode
The standout feature. run_interactive injects a TCP server into the running game as a temporary autoload, giving the AI a live, two-way channel to the game:
You want to... | Use |
Drive the game |
|
Batch a test run |
|
Inspect live state |
|
Mutate live state |
|
Synchronize on events |
|
See / control time |
|
The TCP connection is persistent (single socket reused across commands). Everything is cleaned up automatically when the game stops — the injected autoload is removed and project.godot is restored.
Efficient Testing Patterns
send_key_sequence is the primary tool for gameplay testing. It bundles keys, InputMap actions, waits, state snapshots, screenshots, and signal collection into a single round-trip — much faster than calling individual tools in a loop.
Fast gameplay test (1 round-trip):
send_key_sequence({
keys: ["1", {"action": "move_right", "hold_ms": 300}, {"state": true}, "o", {"wait": 2000}, {"screenshot": "mid.png"}, "s"],
collectSignals: [{nodePath: "/root/EventBus", signals: ["task_completed", "score_changed"]}]
})
// Response includes:
// keys_sent: 4
// states: [{state: {scene: "Desktop", score: 100}, index: 2}]
// screenshots: [{path: "mid.png", size: "1024x768", index: 3}]
// events: [{signal: "score_changed", node: "/root/EventBus", args: [200]}]Avoid these slower patterns:
// BAD: 3 round-trips for the same result
subscribe_signals({nodePath: "/root/EventBus", signals: ["task_completed"]})
send_key_sequence({keys: ["1", "a", "o", "s"]})
get_signal_events()
// BAD: N round-trips instead of 1
send_key({key: "a"})
game_state()
send_key({key: "b"})
game_screenshot()
// BAD: shell sleeps between inputs — use {"wait": ms} checkpoints instead
send_input({action: "move_right"})
Bash("sleep 2")
send_input({action: "jump"})
game_screenshot()Prefer structured checks over screenshots. game_state, evaluate_expression, and get_runtime_errors return text in milliseconds; a screenshot costs a viewport capture, a PNG write, and an image read. Reach for game_screenshot only when the visual result itself is what needs verifying (rendering, layout, animation).
When to use subscribe_signals instead: Only when you need to monitor signals across multiple separate commands (e.g., subscribe once, then issue several unrelated tool calls and check accumulated events later).
Configuration
All configuration happens through environment variables in your MCP client config:
Variable | Description |
| Path to Godot executable (overrides auto-detection) |
| Set to |
| Comma-separated tool categories to enable (e.g., |
| Comma-separated tool names to exclude (e.g., |
| Set to |
The server tries to auto-detect Godot in common install locations. If it can't find it, set GODOT_PATH explicitly.
Tool filtering
Reduce token overhead and add safety by controlling which tools are exposed. All three filters can be combined:
Toolsets — only expose specific categories:
"MCP_TOOLSETS": "scene,node,script,analysis". Available:process,project,scene,node,animation,tilemap,resource,script,signal_group,uid,settings,interactive,screenshot,analysis,testing.Read-only mode —
"MCP_READ_ONLY": "true"blocks every tool that creates, modifies, or deletes files or game state, leaving only readers likeget_scene_tree,read_script,validate_scene,game_state,find_nodes.Exclusion — remove individual tools by name:
"MCP_EXCLUDE_TOOLS": "export_project,manage_autoloads".
{
"godot": {
"command": "node",
"args": ["/path/to/godot-mcp/build/index.js"],
"env": {
"GODOT_PATH": "/path/to/godot",
"MCP_TOOLSETS": "scene,node,script,analysis",
"MCP_READ_ONLY": "true"
}
}
}Supported Clients
MCP is an open standard. Any AI assistant that supports MCP can use this server:
Client | MCP Support | Notes |
Built-in | First-class MCP support via | |
Built-in | VS Code extension, configure in sidebar | |
Built-in | Settings > Features > MCP | |
Built-in | Settings > MCP | |
Built-in | config.json MCP section | |
Plugin | Check MCP plugin availability |
The server speaks the stateless MCP 2026-07-28 protocol revision (built on MCP SDK v2): modern clients call tools directly with no initialize handshake, and the tool list ships cache hints so clients don't re-fetch it. Older 2025-era clients work too — the server auto-detects the client's protocol era per connection and serves the legacy handshake when needed.
You don't connect the LLM to the MCP server directly. Instead, you need an MCP client (an app that speaks the MCP protocol) sitting between your LLM and the MCP server:
Your local LLM (LlamaCPP) --> MCP Client (e.g., Cline) --> Godot MCP Server
runs on localhost:8080 handles tool calls controls GodotHere's how to set it up with LlamaCPP + Cline (the easiest path):
1. Start LlamaCPP with a tool-capable model
llama-server -m your-model.gguf --port 8080Use a model that supports function/tool calling (e.g., Qwen 2.5, Mistral, Llama 3.1+). Smaller models may struggle with complex tool use.
2. Install Cline in VS Code
Install the Cline extension from the VS Code marketplace.
3. Point Cline to your local LLM
In Cline settings, configure the API provider:
API Provider: OpenAI Compatible
Base URL:
http://localhost:8080/v1API Key:
not-needed(any non-empty string)Model ID: the model name your server reports
4. Add the Godot MCP server to Cline (see Quickstart)
5. Test it
Ask Cline: "Use the get_godot_version tool" — if it returns a version, the full chain is working.
Other local LLM setups:
Ollama: Same as above, but base URL is
http://localhost:11434/v1LM Studio: Has built-in MCP support via plugins — check their docs
Custom client: Implement the MCP client spec yourself — the server uses stdio transport and doesn't care what LLM is behind the client
Architecture
The server uses three execution strategies:
Direct CLI — Simple operations (launch editor, get version, read files) call Godot CLI commands or manipulate files directly from TypeScript.
Bundled GDScript — Complex scene operations use
godot_operations.gd, a comprehensive script that runs viagodot --headless --scriptto manipulate scene trees, nodes, and resources through the Godot API.TCP Input Receiver — Interactive mode injects
input_receiver.gdas a temporary autoload that listens on port 9876 for JSON commands (input injection, state queries, viewport capture).
Troubleshooting
Problem | Solution |
"Godot not found" | Set |
Tools not showing up | Restart your AI assistant after adding the MCP config |
"Not a valid Godot project" | Ensure the path you give contains a |
Interactive mode not responding | Check that port 9876 is not in use by another process |
Build errors after cloning | Run |
Permission errors (macOS/Linux) | Make sure |
Contributing
pnpm install
pnpm run build
pnpm test # run all tests (requires Godot installed)
pnpm lint # eslint
pnpm format:check # prettier
pnpm typecheck # tsc --noEmitCI runs all five checks on every push — please run them locally before opening a PR.
License
MIT — see LICENSE.
Available Tools
75 toolsadd_animationA
Add an animation with tracks and keyframes to an existing AnimationPlayer node. To create the AnimationPlayer itself, use create_animation_player first.
Inputs: nodePath (required), scenePath (required), projectPath (required), animationName (required), +3 more.
add_nodeA
Add a child node to a scene file on disk. Defaults to root if parentNodePath is omitted. For sub-scene instances, use instantiate_scene.
Inputs: nodeName (required), nodeType (required), scenePath (required), projectPath (required), +2 more.
add_to_groupB
Add a node to one or more groups in a scene
Inputs: groups (required), nodePath (required), scenePath (required), projectPath (required).
attach_scriptA
Attach a GDScript file to an existing node in a scene
Inputs: nodePath (required), scenePath (required), scriptPath (required), projectPath (required).
batch_operationsA
Execute multiple scene operations in a single Godot process invocation. Much faster than individual tool calls since each spawns a separate process. Use for 3+ operations.
Inputs: operations (required), projectPath (required).
call_methodA
Invoke a method on a live node in a running interactive Godot project. Resolves the node by path relative to the current scene (e.g., "Player", "World/Enemies/Boss") and calls the named method with optional arguments. Returns the serialized result. The project must be running via run_interactive.
Inputs: method (required), nodePath (required), args.
capture_screenshotARead-onlyIdempotent
Render a scene file statically and save the viewport as a PNG. No running game needed. For live game captures, use game_screenshot or run_and_capture. Requires a display server.
Inputs: projectPath (required), width, height, scenePath, +2 more.
connect_signalA
Connect a signal from one node to a method on another node in a scene file (.tscn) on disk. For runtime signal monitoring, use subscribe_signals or send_key_sequence.
Inputs: scenePath (required), methodName (required), signalName (required), projectPath (required), +2 more.
create_animation_playerA
Create an AnimationPlayer node in a scene with optional pre-configured animations. To add animations to an existing player, use add_animation.
Inputs: scenePath (required), projectPath (required), nodeName, animations, +1 more.
create_resourceB
Create a .tres resource file with typed properties
Inputs: projectPath (required), resourcePath (required), resourceType (required), properties, +1 more.
create_sceneA
Create a new Godot scene (.tscn) file with a root node. Specify rootNodeType (e.g., 'Node2D', 'Node3D', 'Control'; defaults to 'Node2D').
Inputs: scenePath (required), projectPath (required), rootNodeType.
create_tilesetA
Create a TileSet resource with atlas sources from texture files
Inputs: projectPath (required), atlasSources (required), resourcePath (required), tileSize, +1 more.
discover_toolsARead-onlyIdempotent
List available tools by category. Categories: process, project, scene, node, animation, tilemap, resource, script, signal_group, uid, settings, interactive, screenshot, analysis, testing, assets, meta.
Inputs: category.
duplicate_nodeA
Duplicate a node within a scene, optionally with a new name or different parent
Inputs: nodePath (required), scenePath (required), projectPath (required), newName, +1 more.
edit_project_settingsA
Modify project.godot settings (input actions, display, rendering, physics, etc.). For autoload singletons, prefer manage_autoloads.
Inputs: settings (required), projectPath (required).
evaluate_expressionARead-onlyIdempotent
Execute an arbitrary GDScript expression at runtime and return the result. The expression runs in the context of the current scene (e.g., "get_tree().current_scene.name", "Vector2(1,2).length()"). Useful for debugging, querying state, and one-off calculations. The project must be running via run_interactive.
Inputs: expression (required).
execute_scriptA
Execute a multi-line GDScript block at runtime in the current scene context. Unlike evaluate_expression, supports variables, loops, and control flow. Requires run_interactive.
Inputs: code (required).
export_mesh_libraryB
Export a scene as a MeshLibrary resource
Inputs: scenePath (required), outputPath (required), projectPath (required), meshItemNames.
export_projectA
Export a Godot project for a target platform using a configured export preset
Inputs: preset (required), outputPath (required), projectPath (required), debug.
find_nodesARead-onlyIdempotent
Search the live runtime scene tree by name pattern and/or type, including dynamically spawned nodes. For static .tscn analysis, use get_scene_tree. Requires run_interactive.
Inputs: pattern, typeFilter.
game_screenshotARead-onlyIdempotent
Capture a screenshot from a running interactive project. Slowest verification path — use only when visual appearance itself matters (rendering, layout, animation). For gameplay/logic checks prefer game_state, evaluate_expression, or get_runtime_errors: structured, and much faster than writing and reading an image. For inline captures during input, use send_key_sequence with {"screenshot": "path"}. Requires run_interactive.
Inputs: outputPath.
game_stateARead-onlyIdempotent
Fast structured verification (preferred over game_screenshot for gameplay logic): returns current scene name, script variables of all autoload singletons, and Player position if a Player node exists. For state not exposed via autoloads, use evaluate_expression or get_node_properties. For inline state captures during input, use send_key_sequence with {"state": true}. Requires run_interactive.
Inputs: no named parameters.
get_debug_outputARead-onlyIdempotent
Get console output (stdout/stderr) from a running Godot project. Supports errors_only and tail filters. For structured errors with stack traces, use get_runtime_errors.
Inputs: tail, errorsOnly.
get_godot_versionARead-onlyIdempotent
Get the installed Godot version
Inputs: no named parameters.
get_node_insightsARead-onlyIdempotent
Analyze a GDScript file: classify methods, identify signals, map dependencies, and list exports. Takes a scriptPath, not a nodePath. Runs headless (no game needed).
Inputs: scriptPath (required), projectPath (required).
get_node_propertiesARead-onlyIdempotent
Read properties from a node in a saved scene file (.tscn) on disk. Returns all non-default properties, or specific ones if listed. For runtime properties, use evaluate_expression.
Inputs: nodePath (required), scenePath (required), projectPath (required), properties.
get_performance_metricsARead-onlyIdempotent
Retrieve performance metrics (FPS, draw calls, memory, node count, etc.) from a running project. Optionally filter to specific metrics. Requires run_interactive.
Inputs: metrics.
get_project_infoCRead-onlyIdempotent
Retrieve metadata about a Godot project
Inputs: projectPath (required).
get_runtime_errorsARead-onlyIdempotent
Retrieve runtime errors, warnings, and backtraces since the last call. Returns structured entries with error type, source, and stack traces. Requires Godot 4.5+ and run_interactive.
Inputs: clear.
get_scene_insightsARead-onlyIdempotent
Analyze a scene's architecture: type distribution, signals, sub-scenes, scripts, groups, and tree depth. Runs headless (no game needed).
Inputs: scenePath (required), projectPath (required).
get_scene_treeARead-onlyIdempotent
Read a scene's node tree from a .tscn file on disk as JSON (names, types, properties, hierarchy). No running game required. For architecture analysis, use get_scene_insights.
Inputs: scenePath (required), projectPath (required).
get_signal_eventsARead-onlyIdempotent
Retrieve buffered signal events from subscribe_signals. Returns signal name, arguments, and timestamp; clears buffer by default. Requires run_interactive.
Inputs: clear.
get_tile_dataARead-onlyIdempotent
Read existing tile cells from a TileMapLayer node in a scene
Inputs: nodePath (required), scenePath (required), projectPath (required).
get_uidARead-onlyIdempotent
Get the UID for a specific file in a Godot project (for Godot 4.4+)
Inputs: filePath (required), projectPath (required).
install_assetA
Download an asset from the Godot Asset Library and extract it into a project. Provide assetId (download URL and sha256 are resolved and verified via the Asset Library) or a direct downloadUrl. The archive's single wrapping folder is stripped by default so addons land under res://addons/. Files are written into the project (existing files at the same path are overwritten) and imported the next time the project is opened or run. Archive entries that would escape the project directory are rejected.
Inputs: projectPath (required), assetId, libraryUrl, verifyHash, +3 more.
instantiate_sceneA
Add a scene as a child instance of another scene (e.g., spawn a player scene inside a level)
Inputs: scenePath (required), projectPath (required), childScenePath (required), nodeName, +2 more.
launch_editorA
Launch the Godot editor GUI for a project. Does not run the game — use run_project or run_interactive for that.
Inputs: projectPath (required).
list_input_actionsARead-onlyIdempotent
List all input actions defined in a project's project.godot (the InputMap). Useful before using send_input. No running game required.
Inputs: projectPath (required).
list_projectsARead-onlyIdempotent
List Godot projects in a directory
Inputs: directory (required), recursive.
load_spriteB
Load a sprite into a Sprite2D node
Inputs: nodePath (required), scenePath (required), projectPath (required), texturePath (required).
manage_autoloadsA
Add, remove, or list autoload singletons in project.godot
Inputs: action (required), projectPath (required), name, scriptPath.
pause_gameA
Pause or unpause a running project. MCP receiver stays active for screenshots, state queries, and property changes while paused. Requires run_interactive.
Inputs: paused.
read_scriptARead-onlyIdempotent
Read the contents of a GDScript file from a Godot project. Returns the full source code as text.
Inputs: scriptPath (required), projectPath (required).
remove_from_groupADestructive
Remove a node from one or more groups in a scene
Inputs: groups (required), nodePath (required), scenePath (required), projectPath (required).
remove_nodeADestructive
Remove a node (and its children) from a scene
Inputs: nodePath (required), scenePath (required), projectPath (required).
rename_nodeA
Rename a node in a scene file. Updates the node's name while keeping all properties, children, and connections intact.
Inputs: newName (required), nodePath (required), scenePath (required), projectPath (required).
reparent_nodeA
Move a node to a different parent within the same scene
Inputs: nodePath (required), scenePath (required), projectPath (required), newParentPath (required).
reset_sceneADestructive
Reload the current scene in a running interactive Godot project. Useful for resetting game state during test loops. The project must be running via run_interactive.
Inputs: no named parameters.
run_and_captureARead-onlyIdempotent
Run the project for a duration, capture a screenshot, then stop. Runs the full game (unlike capture_screenshot) without needing run_interactive (unlike game_screenshot). Requires a display server.
Inputs: projectPath (required), scene, duration, outputPath.
run_interactiveA
Run a Godot project with MCP input receiver injected. Enables send_key_sequence (batched inputs + checkpoints), game_state, get_runtime_errors, and screenshots via TCP. Use instead of run_project for interactive testing.
Inputs: projectPath (required), scene.
run_projectA
Run the Godot project non-interactively and capture console output. No input, screenshots, or state queries — use run_interactive for those.
Inputs: projectPath (required), scene.
run_testsARead-onlyIdempotent
Run GUT (Godot Unit Testing) tests via headless Godot. Requires GUT installed (addons/gut/). Returns pass/fail summary and console output.
Inputs: projectPath (required), testDir, timeout, logLevel, +4 more.
save_sceneA
Save a scene file, optionally to a new path via newPath (creating a copy). Most editing tools save automatically; use this primarily for saving copies.
Inputs: scenePath (required), projectPath (required), newPath.
search_assetsARead-onlyIdempotent
Search the Godot Asset Library for addons and project templates. Returns matching assets with the asset_id you pass to install_asset. Read-only network call to the public Asset Library REST API.
Inputs: page, sort, type, query, +5 more.
send_inputA
Send a single Godot InputMap action (e.g., 'move_up', 'jump') to a running interactive project. Returns delivery confirmation only, not the effect — for multi-step testing prefer send_key_sequence with {"action": ...} items, which batches inputs, waits, and state/screenshot checkpoints into one round-trip (no shell sleeps needed). Requires run_interactive.
Inputs: action (required), pressed.
send_joypad_buttonA
Send a gamepad button event (A, B, X, Y, shoulders, dpad, start, etc.) to a running project. For input actions, prefer send_input. Requires run_interactive.
Inputs: button (required), device, pressed.
send_joypad_motionA
Send a gamepad analog stick or trigger axis event. Simulates analog input with float precision. For input actions, prefer send_input. Requires run_interactive.
Inputs: axis (required), value (required), device.
send_keyA
Send a single keyboard key event to a running interactive Godot project. Supports any key name recognized by Godot (e.g., "space", "a", "escape", "f1") and modifier keys. For sending multiple keys, prefer send_key_sequence — it processes all keys server-side in one round-trip with optional state/screenshot checkpoints. The project must be running via run_interactive.
Inputs: key (required), alt, ctrl, meta, +2 more.
send_key_sequenceA
Primary gameplay testing tool. Sends multiple raw keys and/or InputMap actions in one round-trip with inline checkpoints: {"wait": ms} delays, {"state": true} state snapshots, {"screenshot": "path"} captures, collectSignals for signal events. Replaces send_input/send_key loops with shell sleeps and separate verification calls. Requires run_interactive.
Inputs: keys (required), delayMs, collectSignals.
send_mouse_clickA
Send a mouse click (press+release) at specific coordinates. For cursor movement, use send_mouse_motion. For dragging, use send_mouse_drag. Requires run_interactive.
Inputs: x (required), y (required), button, doubleClick.
send_mouse_dragA
Send a mouse drag (press, move, release) from one position to another. For simple clicks, use send_mouse_click. Requires run_interactive.
Inputs: toX (required), toY (required), fromX (required), fromY (required), +2 more.
send_mouse_motionA
Move the mouse cursor to specific coordinates without clicking. Use for hover effects, aiming, and cursor tracking. Requires run_interactive.
Inputs: x (required), y (required).
set_cellsC
Set tile cells on a TileMapLayer node in a scene
Inputs: cells (required), nodePath (required), scenePath (required), projectPath (required).
set_collision_layer_maskA
Set collision layer and/or mask on a physics node. Accepts layer numbers (1-32) as array or raw bitmask.
Inputs: nodePath (required), scenePath (required), projectPath (required), collisionMask, +1 more.
set_custom_tile_dataB
Set custom data layer values on specific tile cells in a TileMapLayer
Inputs: cells (required), nodePath (required), scenePath (required), projectPath (required).
set_node_propertiesA
Set properties on a node in a saved scene file (.tscn) on disk permanently. For live runtime changes, use set_property instead.
Inputs: nodePath (required), scenePath (required), properties (required), projectPath (required).
set_propertyA
Set a property on a live node at runtime. Changes are immediate but NOT saved to disk — use set_node_properties for permanent changes. Requires run_interactive.
Inputs: value (required), nodePath (required), property (required).
stop_projectADestructive
Stop the currently running Godot project. Does not affect the editor launched via launch_editor.
Inputs: no named parameters.
subscribe_signalsA
Subscribe to signals on a node for persistent monitoring. Retrieve with get_signal_events. For single-sequence monitoring, prefer send_key_sequence with collectSignals. Requires run_interactive.
Inputs: signals (required), nodePath (required).
update_project_uidsA
Update UID references in a Godot project by resaving resources (for Godot 4.4+)
Inputs: projectPath (required).
validate_sceneARead-onlyIdempotent
Validate a scene for common issues (missing scripts, broken references, orphan nodes)
Inputs: scenePath (required), projectPath (required).
validate_scriptARead-onlyIdempotent
Validate a GDScript file for syntax errors using Godot's parser in headless mode. No running game needed.
Inputs: scriptPath (required), projectPath (required).
wait_for_nodeARead-onlyIdempotent
Block until a node appears in the scene tree. Useful for waiting on dynamically spawned nodes (e.g., wait for "Player/Sword" to appear after equip). Returns whether the node was found or the wait timed out. The project must be running via run_interactive.
Inputs: nodePath (required), timeout.
wait_for_signalARead-onlyIdempotent
Block until a signal is emitted on a node in the running game. Useful for sequencing test steps (e.g., wait for "animation_finished" or "died"). Returns whether the signal was received or the wait timed out. The project must be running via run_interactive.
Inputs: signal (required), nodePath (required), timeout.
write_scriptA
Write or overwrite a GDScript file in a Godot project. Creates parent directories if needed. Use validate_script afterward to check for syntax errors.
Inputs: content (required), scriptPath (required), projectPath (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 75 tools
Most tools have distinct resource+action mappings, and overlapping tools (send_input/send_key/send_key_sequence, set_property/set_node_properties) are clearly differentiated by descriptions that cross-reference the preferred choice. However, the sheer number of similar runtime/input/screenshot tools creates some initial ambiguity.
All tool names follow a consistent snake_case verb_noun pattern (e.g., list_projects, create_scene, remove_node, validate_script). No camelCase or mixed styles, making the API predictable.
75 tools is far beyond the typical well-scoped MCP server. Even for a broad engine like Godot, this feels bloated; many tools are micro-utilities that could be consolidated (e.g., several separate mouse/key/joypad senders).
The surface covers scene editing, project settings, scripts, tilemaps, animation, input simulation, testing, and asset management. Minor gaps include no file-level delete for scenes/resources/scripts and no create-project tool, but for the primary game-dev workflow it's largely complete.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
An MCP server that integrates with Discord to provide AI-powered features.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
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.444MIT
- 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
- AlicenseCqualityCmaintenanceAn MCP server providing AI assistants with 149 tools to fully control the Godot game engine, including runtime code execution, scene manipulation, physics, audio, networking, animation, and more.10098 npm515MIT