Godot Toolkit

Give an MCP client a structured, Godot-aware way to inspect, author, run, test, and debug Godot 4 projects.

Godot 4 Node.js 18+ MCP License 中文文档

简体中文 · 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.

[!TIP] 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 build

npm.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.gd

3. Enable the plugin in Godot

1. Open the target Godot project.
2. Open Project → Project Settings → Plugins.
3. Enable Godot MCP Toolkit.
4. 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_info to 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.

Choose Your Path

You want to…	Start with…	Plugin required?
Inspect or modify project files, scenes, scripts, and resources	Headless workflow	No
Edit an open scene with Godot context, selection, and Undo/Redo	Editor Bridge	Yes
Inspect and control a running game	Runtime workflow	Yes
Keep the MCP tool list small	Tool groups	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	get_project_info, export presets, safe project export, file search, resources, UIDs, project context	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=0 only for a 45-tool headless-only surface, or use GODOT_MCP_TOOL_GROUPS for 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 the godot / godot4 command on PATH.
• 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 build

The 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 build

Restart 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:

1. get_server_info — confirms the server is reachable and reports capabilities.
2. get_godot_version — confirms the Godot executable can be launched.
3. get_project_info — reads project metadata and selected settings.
4. 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.

1. Copy godot/addons/godot_mcp_pro into the target project as addons/godot_mcp_pro.
2. In Godot, open Project Settings > Plugins and enable Godot MCP Toolkit.
3. Keep the target project open. The plugin starts its project-specific local bridge automatically.
4. Call get_editor_info or bind_editor; the first live request establishes the one-to-one conversation binding.
5. For runtime control, call run_project, then get_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 with headless: false, and return the runId, 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	project,scenes,nodes,scripts,resources,performance,ai,diagnostics
2D level and UI work	editor,ui,effects,project,scenes,nodes,scripts,visuals,tilemap
3D blockout and deep authoring	editor,advanced_editor,deep_authoring,professional_workflows,effects,project,scenes,nodes,animation,resources
Runtime test and debugging	runtime,runtime_diagnostics,performance,diagnostics
Full workstation setup	all

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

1. Call get_project_info, list_scenes, and get_game_context.
2. Ask the assistant to identify the relevant scene, scripts, and resources.
3. Make focused changes with project, scene, script, or live Editor tools.
4. Run check_project, analyze_script, and run_automation_test before 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

1. Enable the Editor Bridge and call bind_editor.
2. Create a hierarchy with create_ui_screen and create_ui_component.
3. Refine layout with configure_control_layout, theme with set_theme_override, and structure with inspect_ui_layout.
4. 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

1. Run the project and call get_runtime_info to establish the runtime binding.
2. Inspect the remote tree and configure watches for health, velocity, or state.
3. Poll poll_runtime_observability while reproducing the issue.
4. Inject keyboard, mouse, touch, wheel, or drag input and capture evidence.
5. Finish with release_runtime_binding and stop_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
GODOT_BIN	No	Preferred Godot executable path for local launches and portable helpers.
GODOT_PATH	No	Alternate Godot executable path used by the MCP server configuration.
GODOT_MCP_PROJECT	No	Default absolute project path for project-facing operations.
GODOT_MCP_ENABLE_EDITOR_BRIDGE	No	Live tools are automatic; set to 0 only to disable and hide Editor/Runtime bridge tools.
GODOT_MCP_TOOL_GROUPS	No	Comma-separated tool groups, or all.
GODOT_MCP_RUNTIME_PORT	No	Override the runtime port used for a launched project.
GODOT_MCP_EXTENSIONS_DIR	No	Directory containing optional .mjs tool extensions.

Session Safety

• Project-facing operations use an explicit absolute projectPath unless GODOT_MCP_PROJECT is 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_binding or release_runtime_binding before 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
Capabilities	scan supported operation families
Editor Bridge and Runtime Agent	enable the plugin, understand ports, or release a binding
Multi-project usage	work safely across projects or Godot versions
Compatibility	check MCP protocol and Godot support expectations
Roadmap	see active and planned deep-editor areas
Contributing	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 build

The 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.