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 · Compatibility · Roadmap

Godot MCP Toolkit connects an MCP client to Godot through deterministic headless operations, an optional live Editor Bridge, and a Runtime Agent. The result is a workflow that starts with project understanding and ends with verified scene changes or runtime evidence—without relying on fragile screen-coordinate automation.

Choose Your Path

Related MCP server: Godot MCP

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.

What It Covers

See the complete operation inventory in docs/capabilities.md.

Tool inventory: 45 headless tools by default, or 164 unique built-in tools when the Editor Bridge is enabled with GODOT_MCP_TOOL_GROUPS=all. The detailed inventory is organized into 23 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 features are opt-in. They require the plugin and remain out of the default workflow when you only need headless automation.

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. Add the following variables to the MCP server entry:

{
  "GODOT_MCP_ENABLE_EDITOR_BRIDGE": "1",
  "GODOT_MCP_TOOL_GROUPS": "all"
}

4. Reload the Godot project and reconnect the MCP client.

5. Call bind_editor before editing the open Editor.

6. For runtime control, call run_project, then get_runtime_info.

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.

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:

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

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

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.