Godot MCP Toolkit
This server provides a comprehensive MCP toolkit for Godot 4, enabling headless project and scene authoring, script management, runtime control, and project analysis.
Project Management: Create, inspect, configure, and discover Godot projects.
File Operations: List, read, write, and search project files and resources (with safe relative paths).
Scene & Node Authoring: Create, inspect, duplicate, modify, and save scenes; add/remove nodes, set properties, load sprites, and create UI nodes.
Scripting: Create, attach, and analyze GDScript files.
Animation & Tilemaps: Create animations, inspect animation players, and edit tilemap cells.
Runtime Control & Testing: Run projects in the background, capture debug output, simulate input, run automation tests, stop processes, and launch the editor.
Diagnostics & Profiling: Check projects for parser/runtime issues and profile scene frame/memory performance.
Resources & UIDs: List resources, find references, read/write resource UIDs, and update project UIDs.
Visuals: Capture screenshots of scenes.
AI Context: Build a project context graph to aid AI understanding.
Live Editor Bridge (plugin): Connect to a running Godot Editor to interact with its scene tree, Inspector, viewports, UI, effects, animations, navigation, physics, audio, themes, plugins, and workspace state.
Runtime Agent (plugin): Inspect and control a running game—examine remote nodes, call methods, pause/resume/step execution, inject input, capture screenshots, query physics/navigation, control audio, watch values, and collect logs/performance metrics.
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 Toolkit Capture a screenshot of the running game"
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 Toolkit
Give an MCP client a structured, Godot-aware way to inspect, author, run, test, and debug Godot 4 projects.
简体中文 · Detailed tutorial (中文) · Capabilities · Editor Bridge · Window-level Computer Use (中文) · Compatibility · Roadmap
Godot MCP Toolkit connects an MCP client to Godot through deterministic headless operations, a live Editor Bridge, a Runtime Agent, and window-level Computer Use. The default distribution exposes 174 built-in MCP tools covering projects, scenes, nodes, scripts, 2D, 3D, UI, skeletons, animation, navigation, physics, audio, runtime debugging, performance observation, and window input.
The repository can live anywhere on your computer. E:\Tools\godot-mcp-toolkit, D:\Dev\godot-mcp-toolkit, and other locations work as long as your MCP client points to the actual build/index.mjs path.
Ask for outcomes instead of clicks: “Create a responsive pause menu”, “add a camera and key light to the arena”, or “run the scene and report health changes plus frame time.”
Install and Connect in 5 Minutes
The following Windows flow is the complete setup. Run these commands in a terminal opened after cloning the repository.
1. Clone and build the MCP server
git clone https://github.com/woyucbugongdaitian/godot-mcp-toolkit.git
Set-Location godot-mcp-toolkit
npm.cmd install
npm.cmd run buildnpm.cmd install installs the Node.js dependencies, including WebSocket support. npm.cmd run build generates the MCP client entry point at build/index.mjs.
Run them again only after updating the repository, changing dependencies, or removing node_modules / build. The MCP client should launch build/index.mjs, not an outdated source entry.
2. Copy the Godot plugin
Update $project and run this from the Toolkit repository root:
$toolkit = (Get-Location).Path
$project = "E:\Games\MyGodotProject"
New-Item -ItemType Directory -Force "$project\addons" | Out-Null
Copy-Item "$toolkit\godot\addons\*" "$project\addons" -Recurse -Force
Test-Path "$project\addons\godot_mcp_pro\plugin.cfg"The last command must return True. The target project must contain:
MyGodotProject/
├─ project.godot
└─ addons/
└─ godot_mcp_pro/
├─ plugin.cfg
├─ plugin.gd
└─ runtime_agent.gd3. Enable the plugin in Godot
Open the target Godot project.
Open Project → Project Settings → Plugins.
Enable Godot MCP Toolkit.
Keep that Godot editor window open.
After it is enabled, the plugin starts the project-local Editor Bridge and Runtime Agent automatically. No GODOT_MCP_ENABLE_EDITOR_BRIDGE=1 setting or second connection switch is required.
4. Add the MCP server to your AI client
Replace the three local paths in this configuration:
{
"mcpServers": {
"godot-mcp-toolkit": {
"command": "node",
"args": ["E:/Tools/godot-mcp-toolkit/build/index.mjs"],
"env": {
"GODOT_PATH": "E:/Tools/Godot/Godot.exe",
"GODOT_MCP_PROJECT": "E:/Games/MyGodotProject"
}
}
}
}Restart the MCP client and ask:
Connect to the currently open Godot project and call
get_editor_infoto verify the Editor Bridge. Do not launch or close any Godot editor.
Once Godot version, project path, and bridge port are returned, the connection is ready.
5. Optional Windows installer
From the repository root:
.\portable\install.ps1 `
-ProjectPath "E:\Games\MyGodotProject" `
-GodotPath "E:\Tools\Godot\Godot.exe"The helper copies the plugin and generates mcp-config.generated.json. You still need to enable the plugin in Godot once.
Related MCP server: Godot MCP
Choose Your Path
You want to… | Start with… | Plugin required? |
Inspect or modify project files, scenes, scripts, and resources | No | |
Edit an open scene with Godot context, selection, and Undo/Redo | Yes | |
Inspect and control a running game | Yes | |
Keep the MCP tool list small | No |
At a Glance
flowchart LR
Client["MCP client / AI assistant"] --> Server["Godot MCP Toolkit\nNode.js MCP server"]
Server --> Headless["Headless Godot\nfiles · scenes · checks · tests"]
Server --> Bridge["Editor Bridge\nopen Godot Editor"]
Server --> Agent["Runtime Agent\nrunning game"]
Bridge --> Editor["scene tree · Inspector · 2D · 3D · UI"]
Agent --> Game["input · properties · logs · metrics"]Three connected modes
Headless automation — discover projects, create scenes, edit nodes and resources, generate or validate GDScript, capture screenshots, run tests, inspect TileMaps, and profile scenes.
Live Editor Bridge — work with the currently open Godot Editor: scene tree, Inspector properties, selections, 2D/3D content, UI, effects, animation, navigation, physics, audio, themes, plugins, and workspace state.
Runtime Agent — inspect remote nodes and properties, call methods, pause/resume/step, inject keyboard or pointer input, capture screenshots, query ray, point, and primitive-shape physics overlaps, query navigation paths, control audio, watch values, and collect logs or frame metrics.
Window Control — bind one MCP conversation to one Godot Editor or game window; games default to Godot virtual input that does not move the real mouse, while Editor control uses verified Windows native window input.
What It Covers
Area | Examples | Typical result |
Project intelligence and delivery |
| Understand, validate, and deliver an unfamiliar project |
Scene authoring | Create, inspect, duplicate, save, add, move, rename, remove, and configure nodes | Make reproducible scene changes from structured requests |
2D and UI | Sprites, Control nodes, cameras, lights, UI screens, layout, Theme overrides | Build menus, HUDs, dialogs, and 2D prototypes |
3D authoring | Primitive and editable ArrayMesh surfaces, cameras, lights, transforms, StandardMaterial, stylized rendering | Block out, inspect, and revise a playable 3D scene |
Gameplay and production systems | AnimationTree state machines, Bezier curves, Skeleton/Skin, Navigation baking, collision contacts, Audio Bus effects, imports, and exports | Set up and validate production workflows without hiding changes in generated files |
Runtime verification | Remote tree/properties, input injection, screenshots, physics/navigation queries, structured logs, performance snapshots, contacts, and audio analysis | Reproduce issues and verify behavior with evidence |
See the complete operation inventory in docs/capabilities.md.
Tool inventory: 174 unique built-in tools are available by default. Set
GODOT_MCP_ENABLE_EDITOR_BRIDGE=0only for a 45-tool headless-only surface, or useGODOT_MCP_TOOL_GROUPSfor a focused tool list. The detailed inventory is organized into 24 reader-friendly categories in docs/capabilities.md.
Quick Start
1. Check prerequisites
Node.js 18 or newer.
Godot 4.x available through
GODOT_BIN,GODOT_PATH, or thegodot/godot4command onPATH.An MCP client that can launch a local stdio server.
2. Install and build
git clone https://github.com/woyucbugongdaitian/godot-mcp-toolkit.git
Set-Location godot-mcp-toolkit
npm.cmd install
npm.cmd run buildThe generated entry point is build/index.mjs. Build from the repository root so the server can resolve its bundled Godot operation script.
3. Update an existing installation
If you originally installed by cloning the repository, update it from the Toolkit directory:
git pull
npm.cmd install
npm.cmd run buildRestart the MCP client after the update. If the release includes Godot plugin changes, synchronize the copied plugin into the target project again:
.\portable\install.ps1 `
-ProjectPath "E:\Games\MyGodotProject" `
-GodotPath "E:\Tools\Godot\Godot.exe"The plugin is copied into the target project's addons/godot_mcp_pro; git pull does not update that project copy automatically. The installer creates a timestamped backup before replacing an existing plugin. For a global installation, run portable/install-global.ps1 again after updating the repository. When projects are launched through Open with Godot MCP, the launcher synchronizes the plugin during startup.
4. Add the MCP server
Copy this entry into your MCP client configuration and replace the two paths:
{
"mcpServers": {
"godot-mcp-toolkit": {
"command": "node",
"args": ["E:/Tools/godot-mcp-toolkit/build/index.mjs"],
"env": {
"GODOT_PATH": "E:/Tools/Godot/Godot_v4.x-stable_win64.exe",
"GODOT_MCP_PROJECT": "E:/Games/MyGodotProject"
}
}
}
}GODOT_MCP_PROJECT is optional. If it is omitted, pass an absolute projectPath to each project-facing tool. A ready-to-copy template is available at examples/mcp-config.json.
5. Verify the connection
Ask the MCP client to call these tools in order:
get_server_info— confirms the server is reachable and reports capabilities.get_godot_version— confirms the Godot executable can be launched.get_project_info— reads project metadata and selected settings.get_game_context— builds a compact project graph for the assistant.
If all four calls succeed, the headless workflow is ready. Continue with the detailed tutorial for a full inspect → edit → verify loop.
Enable Live Editor and Runtime Control
Live tools are exposed by the MCP server automatically. The Godot plugin is the only live-control switch you need.
Copy
godot/addons/godot_mcp_prointo the target project asaddons/godot_mcp_pro.In Godot, open Project Settings > Plugins and enable Godot MCP Toolkit.
Keep the target project open. The plugin starts its project-specific local bridge automatically.
Call
get_editor_infoorbind_editor; the first live request establishes the one-to-one conversation binding.For runtime control, call
run_project, thenget_runtime_info.
No GODOT_MCP_ENABLE_EDITOR_BRIDGE=1 setting is required. Set it to 0 only when you intentionally want to hide every live Editor and Runtime tool.
On Windows, the installer can copy the plugin and generate a starter configuration:
.\portable\install.ps1 -ProjectPath "E:\Games\MyGodotProject" -GodotPath "E:\Tools\Godot\Godot_v4.x-stable_win64.exe"The installer does not enable the plugin inside Godot automatically. See docs/editor-bridge.md for binding rules and docs/tutorial.zh-CN.md for a complete walkthrough.
Work with Multiple Godot Projects
Use one named MCP server configuration per project and one conversation per project. Do not reuse one default-project server while asking the same conversation to switch between open projects.
{
"mcpServers": {
"godot-project-a": {
"command": "node",
"args": ["E:/Tools/godot-mcp-toolkit/build/index.mjs"],
"env": {
"GODOT_PATH": "E:/Tools/Godot/Godot.exe",
"GODOT_MCP_PROJECT": "E:/Games/ProjectA"
}
},
"godot-project-b": {
"command": "node",
"args": ["E:/Tools/godot-mcp-toolkit/build/index.mjs"],
"env": {
"GODOT_PATH": "E:/Tools/Godot/Godot.exe",
"GODOT_MCP_PROJECT": "E:/Games/ProjectB"
}
}
}
}Open both Godot projects, enable the plugin in both, then use a separate AI conversation with godot-project-a and godot-project-b. Each MCP server process has its own session ID, so different projects can be controlled concurrently. If one conversation is already bound to Project A, call release_editor_binding before switching that same conversation to Project B; never close Godot to resolve a binding conflict.
If the Game Has Sound but No Window
run_project launches a visible game window by default. Only headless: true hides the window. Ask the AI:
Use the current
build/index.mjs, run the project withheadless: false, and return therunId, PID, and window status. Do not close the Godot editor.
Check that the MCP client points to the latest build/index.mjs, that headless was not set to true, and use get_debug_output(runId) for startup errors. run_project opens the game window; get_editor_info and bind_editor control the already-open Godot editor.
Expose Only the Tools You Need
Set GODOT_MCP_TOOL_GROUPS to a comma-separated list so the MCP client sees only the capabilities relevant to the current task:
Focus | Suggested groups |
Project repair or code generation |
|
2D level and UI work |
|
3D blockout and deep authoring |
|
Runtime test and debugging |
|
Full workstation setup |
|
The editor, ui, effects, advanced_editor, deep_authoring, and professional_workflows groups require the live Editor Bridge. The runtime_diagnostics group requires the Runtime Agent. Remote runtime tools also require the plugin; run_project, output capture, headless input simulation, and automation tests remain available without it.
Workflow Recipes
Understand and improve an existing project
Call
get_project_info,list_scenes, andget_game_context.Ask the assistant to identify the relevant scene, scripts, and resources.
Make focused changes with project, scene, script, or live Editor tools.
Run
check_project,analyze_script, andrun_automation_testbefore moving on.
Example request: “Inspect this project, find the title scene, add a start button that loads the main scene, and run parser checks.”
Build a polished 2D screen
Enable the Editor Bridge and call
bind_editor.Create a hierarchy with
create_ui_screenandcreate_ui_component.Refine layout with
configure_control_layout, theme withset_theme_override, and structure withinspect_ui_layout.Add a transition or visual pass, then capture an Editor screenshot for review.
Example request: “Create a responsive pause menu with Resume, Settings, and Quit actions. Center it, use a dark translucent panel, and add a quick fade-in.”
Debug a running game with live signals
Run the project and call
get_runtime_infoto establish the runtime binding.Inspect the remote tree and configure watches for health, velocity, or state.
Poll
poll_runtime_observabilitywhile reproducing the issue.Inject keyboard, mouse, touch, wheel, or drag input and capture evidence.
Finish with
release_runtime_bindingandstop_project.
Example request: “Launch the current scene, watch the player’s health and movement state, simulate an inventory drag, and report new warnings plus average frame time.”
Configuration Reference
Variable | Required | Purpose |
| No | Preferred Godot executable path for local launches and portable helpers. |
| No | Alternate Godot executable path used by the MCP server configuration. |
| No | Default absolute project path for project-facing operations. |
| No | Live tools are automatic; set to |
| No | Comma-separated tool groups, or |
| No | Override the runtime port used for a launched project. |
| No | Directory containing optional |
Session Safety
Project-facing operations use an explicit absolute
projectPathunlessGODOT_MCP_PROJECTis configured.One MCP conversation binds to one live Editor or Runtime project at a time. Bindings expire after 90 seconds of inactivity.
Editor and Runtime bindings are independent. Call
release_editor_bindingorrelease_runtime_bindingbefore switching projects.Live Editor mutations are designed to participate in Godot’s Undo/Redo flow where the Godot API supports it.
The bridge uses local loopback WebSockets; no cloud relay or external game service is required.
Unsupported Godot 4.x APIs return structured errors instead of terminating the MCP process.
Documentation Map
Guide | Use it when you need to… |
follow a complete install, configuration, editing, runtime, and troubleshooting walkthrough | |
scan supported operation families | |
enable the plugin, understand ports, or release a binding | |
work safely across projects or Godot versions | |
check MCP protocol and Godot support expectations | |
see active and planned deep-editor areas | |
propose changes or run local quality checks |
Current Boundaries
Godot MCP Toolkit focuses on stable semantic operations rather than pixel-level imitation of every Editor panel. ArrayMesh plus Skeleton/Skin editing, BlendSpace foundations, NavigationMesh baking, runtime contacts and structured logs, Audio Bus effect chains/spectrum peaks, Theme fonts/icons/type variations, TileSet terrain/proxy authoring, and safe preset exports are available. Imported-mesh vertex editing, full viewport Gizmo gestures, visual-shader graph tooling, code refactoring/full debugger stacks, importer-setting authoring, Project Manager/Export Dock UI automation, and every editor panel remain outside the semantic API boundary. See docs/roadmap.md for the current boundary.
Development
npm.cmd run check
npm.cmd test
npm.cmd run buildThe test suite covers the MCP contract and one-to-one Editor/Runtime binding behavior.
License
Released under the MIT License. This is an independent community implementation; see NOTICE.md for attribution details.
Available Tools
43 toolsadd_nodeB
Add a node to a scene and save it.
Inputs: nodeName (required), nodeType (required), scenePath (required), parentPath, +2 more.
analyze_scriptB
Run Godot's script checker and return diagnostics.
Inputs: scriptPath (required), timeoutMs, projectPath.
attach_scriptA
Attach a project-relative GDScript to a scene node.
Inputs: nodePath (required), scenePath (required), scriptPath (required), projectPath.
capture_screenshotC
Render a scene in a controlled viewport and save a PNG inside the project.
Inputs: scenePath (required), width, height, outputPath, +1 more.
check_projectA
Run Godot in headless editor mode and return parser/runtime diagnostics.
Inputs: timeoutMs, projectPath.
create_animationC
Create an empty AnimationPlayer animation resource in a scene.
Inputs: scenePath (required), animationName (required), length, nodePath, +1 more.
create_projectC
Create a minimal Godot 4 project with a project.godot file.
Inputs: name, renderer, projectPath, createMainScene.
create_sceneC
Create and save a minimal Godot scene.
Inputs: scenePath (required), rootName, rootType, projectPath.
create_scriptC
Create a GDScript file with a safe starter template.
Inputs: scriptPath (required), body, extends, overwrite, +1 more.
create_ui_nodeB
Add a Control-derived UI node to a scene with optional layout properties.
Inputs: nodeName (required), scenePath (required), nodeType, parentPath, +2 more.
duplicate_sceneB
Copy a scene to another project-relative .tscn path.
Inputs: sourcePath (required), destinationPath (required), projectPath.
find_resource_referencesC
Find text references to a project-relative resource path.
Inputs: resourcePath (required), maxResults, projectPath.
get_capabilitiesA
Return versioned feature groups and compatibility information.
Inputs: no named parameters.
get_debug_outputC
Read captured output from a background Godot run.
Inputs: clear, runId, tailLines, projectPath.
get_game_contextB
Build a compact project graph for AI-assisted game understanding.
Inputs: maxFiles, projectPath, includeScripts.
get_godot_versionA
Read the installed Godot version.
Inputs: godotBinary.
get_project_infoC
Read project.godot metadata and selected settings.
Inputs: projectPath.
get_server_infoB
Return server capabilities and runtime information.
Inputs: no named parameters.
get_uidC
Read a resource UID using Godot's resource database.
Inputs: resourcePath (required), projectPath.
inspect_animation_playersB
Inspect AnimationPlayer nodes and animation names.
Inputs: scenePath (required), projectPath.
inspect_nodeB
Read a node's serializable Inspector properties.
Inputs: scenePath (required), nodePath, projectPath.
inspect_scene_treeA
Inspect a scene tree recursively without modifying the scene.
Inputs: scenePath (required), maxDepth, projectPath.
inspect_tilemapsC
Inspect TileMap and TileMapLayer nodes in a scene.
Inputs: scenePath (required), projectPath.
launch_editorC
Launch the Godot editor for a project and return its process id.
Inputs: godotBinary, projectPath.
list_filesB
List project files with safe, project-relative paths.
Inputs: path, recursive, extensions, maxResults, +1 more.
list_projectsC
Find Godot projects below a directory.
Inputs: root, maxDepth.
list_resourcesC
List project resources filtered by extension.
Inputs: path, extensions, projectPath.
list_scenesB
List all .tscn scenes in a project.
Inputs: path, projectPath.
load_spriteC
Add a Sprite2D using a project-relative texture path.
Inputs: scenePath (required), texturePath (required), nodeName, parentPath, +1 more.
profile_sceneC
Collect lightweight frame and memory counters for a scene.
Inputs: scenePath (required), frames, projectPath.
read_fileB
Read a UTF-8 text file inside a Godot project.
Inputs: path (required), projectPath.
remove_nodeC
Remove a node from a scene and save it.
Inputs: nodePath (required), scenePath (required), projectPath.
run_automation_testA
Run a project-relative GDScript test in headless mode.
Inputs: testPath (required), timeoutMs, projectPath.
run_projectA
Run a Godot project in the background and capture stdout/stderr.
Inputs: scene, headless, godotBinary, projectPath.
save_sceneA
Load and re-save a scene to validate its serialization.
Inputs: scenePath (required), projectPath.
search_projectB
Search UTF-8 project files for a literal or regular expression pattern.
Inputs: pattern (required), path, regex, extensions, +2 more.
set_node_propertyB
Set a serializable node property and save the scene.
Inputs: value (required), nodePath (required), property (required), scenePath (required), +1 more.
set_project_settingA
Set a project.godot setting using section/key notation.
Inputs: value (required), setting (required), projectPath.
set_tile_cellC
Set a TileMap or TileMapLayer cell using Godot's native API.
Inputs: x (required), y (required), nodePath (required), sourceId (required), +6 more.
simulate_inputB
Inject a keyboard or mouse input event while a scene runs headlessly.
Inputs: eventType (required), scenePath (required), keycode, pressed, +3 more.
stop_projectC
Stop a background Godot run.
Inputs: runId, projectPath.
update_project_uidsB
Ask Godot to refresh resource UIDs for a project.
Inputs: projectPath.
write_fileC
Write a UTF-8 text file inside a Godot project.
Inputs: path (required), content (required), projectPath, createDirectories.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Most tools have distinct purposes, but get_server_info and get_capabilities overlap heavily in scope. Additionally, add_node vs load_sprite vs create_ui_node create ambiguity around which node-creation tool to use, though descriptions partially clarify.
All tool names follow a consistent verb_noun snake_case pattern, such as list_scenes, create_project, and inspect_node. There are no deviations or mixed conventions, making the naming highly predictable.
With 43 tools, the server is substantially over the recommended 3-15 range. While the domain is broad, the sheer number creates a heavy cognitive load and suggests insufficient consolidation of related operations.
The toolkit covers core Godot workflows like scene editing, scripting, running, and testing, but lacks basic delete operations for files, scenes, and projects. This leaves notable gaps in lifecycle management, especially since create and duplicate operations exist without corresponding removals.
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Make all the audio for your game from a single prompt. Describe your game and your AI assistant plans every sound it needs (sound effects, ambience loops, music tracks and character voice lines), then generates them all in one go. You get several AI versions of each sound and keep the ones you like. Sounds are organized per game in folders and scenes, and the free Godot plugin installs them into your project, ready to play with one line of code. Works with Claude, Claude Code, Cursor and any MCP client, with OAuth login (no API key needed). Free plan included; sounds can be used in commercial games.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to build, run, and debug Godot projects by editing scenes and scripts, inspecting live game state, injecting input, capturing viewports, and examining native debugger state through 42 tools.European Union Public 1.2
- AlicenseAqualityCmaintenanceEnables AI coding assistants to directly control a running Godot editor for autonomous game development, including scene building, tilemap and animation manipulation, UI automation, and live GDScript execution.46MIT
- AlicenseAqualityCmaintenanceConnects AI assistants to the live Godot 4 editor so they can build scenes, scripts, resources and animations, run the game, simulate input, capture screenshots and playtest scenarios, and diagnose runtime errors. Every edit flows through undoable changesets that can be diffed, approved, checkpointed or discarded.291MIT
- 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