Skip to main content
Glama

Godot MCP 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.

Related MCP server: Godot MCP

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.

Available Tools

43 tools
add_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

    B3/5.0

    Scored across 43 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      A
      quality
      C
      maintenance
      Connects 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.
      29
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      23
      MIT