Godot Devtool

# godot-devtool

English | 中文

Buy me a coffee on Patreon if this project helps you. I am not very familiar with editing Patreon pages yet; thanks for your understanding.

godot-devtool is a Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation. Version 2.8.3 reuses an already connected Godot editor for launch_editor instead of opening a second editor process.

Architecture

MCP client
  -> node build/index.js over stdio
  -> native/headless Godot tools
  -> optional ws://127.0.0.1:8766 bridge
  -> addons/godot_devtool editor plugin
  -> runtime autoload bridge

• The MCP server always runs over stdio.
• Native routes inspect and edit project files without opening the editor.
• Headless routes call Godot for scene/resource/script operations.
• Editor routes use the bundled WebSocket plugin for live selection, Inspector writes, UndoRedo scene mutations, scene save, and plugin reload.
• Runtime routes use the installed autoload bridge for running-game scene tree, properties, input simulation, screenshots, and QA checks.
• Browser visualizer routes serve a local read-only HTTP dashboard for bridge/client status and live-route orientation.

Requirements

• Node.js 18 or newer.
• Godot 4.x. Set GODOT_PATH unless godot is already on PATH.
• An MCP client such as Codex, Claude Code, Cursor, Cline, Roo Code, VS Code Copilot, or another client that can launch stdio MCP servers.
• A Godot project containing project.godot.

Install From Release Zip

1. Download the release build:

   godot-devtool-build-2.8.3.zip

2. Extract it to a stable path, for example:

   Expand-Archive ".\godot-devtool-build-2.8.3.zip" "E:\godot-devtool" -Force
   

3. Confirm the server entry exists:

   Test-Path "E:\godot-devtool\build\index.js"
   Test-Path "E:\godot-devtool\build\addons\godot_devtool\plugin.gd"
   

4. Add this MCP server to your client configuration:

   {
     "mcpServers": {
       "godot-devtool": {
         "command": "node",
         "args": ["E:/godot-devtool/build/index.js"],
         "env": {
           "GODOT_PATH": "D:/Program Files/Godot/Godot_v4.x.exe",
           "GODOT_DEVTOOL_WS_PORT": "8766"
         }
       }
     }
   }
   

   Codex Desktop uses TOML in config.toml:

   [mcp_servers.godot-devtool]
   command = "node"
   args = ["E:/godot-devtool/build/index.js"]
   env = { GODOT_PATH = "D:/Program Files/Godot/Godot_v4.x.exe", GODOT_DEVTOOL_WS_PORT = "8766" }
   

5. Restart the MCP client and ask it to call:

   get_godot_version
   get_capabilities
   get_capabilities {"toolNames":["plugin_install","plugin_status","plugin_cleanup_port"],"includeSchemas":true}
   

GODOT_DEVTOOL_WS_PORT defaults to 8766. If an old godot-devtool process is still holding the port, first call plugin_cleanup_port without kill to inspect the listener. Only call it with kill=true after confirming the listener is the stale process you intend to stop.

Build From Source

git clone https://github.com/wangdiandao/godot-devtool.git
cd godot-devtool
npm install
npm run build

Use build/index.js as the MCP server entry. The bundled Godot addon is copied into build/addons/godot_devtool during npm run build.

Install The Godot Plugin

The plugin is included in the release/build package. It still must be installed into each Godot project that needs live editor or runtime routes.

1. Start your MCP client with godot-devtool configured.

2. Ask the AI or call the tool directly:

   plugin_install
   

   Arguments:

   {
     "projectPath": "E:/my-godot-project",
     "overwrite": true,
     "websocketPort": 8766
   }
   

3. Open the Godot project.

4. Enable the plugin:

   Project > Project Settings > Plugins > godot-devtool > Enable
   

5. Check installation and connection:

   plugin_status
   

For runtime routes, plugin_install also registers:

autoload/DevtoolRuntime = *res://addons/godot_devtool/runtime_bridge.gd

Run the project from Godot before using runtime_ws tools. The editor plugin connects while the editor is open; the runtime bridge connects while the game is running.

Ask AI To Install It

After adding the MCP server to your client, you can paste this prompt into the AI assistant:

Use the godot-devtool MCP server to install and verify the Godot plugin for my project.

Project path: "E:/my-godot-project"
WebSocket port: 8766

Steps:
1. Call get_godot_version and get_capabilities for the lightweight tool catalog.
2. Confirm plugin_install, plugin_status, plugin_reload, and plugin_cleanup_port are available.
3. If you need input schemas, call get_capabilities with toolNames=["plugin_install","plugin_status","plugin_reload","plugin_cleanup_port"] and includeSchemas=true.
4. Call plugin_install with overwrite=true for the project path above.
5. Call plugin_status and summarize installed files, autoload registration, bridge mode, and WebSocket port.
6. Tell me exactly how to enable the plugin in Godot.
7. If runtime routes are needed, tell me to run the project and then verify runtime bridge status.
Do not edit unrelated files.

Chinese prompt:

请使用 `godot-devtool` MCP server 帮我安装并验收 Godot 插件。

项目路径: "E:/my-godot-project"
WebSocket 端口: 8766

步骤:
1. 调用 get_godot_version 和 get_capabilities，先获取轻量工具目录。
2. 确认 plugin_install、plugin_status、plugin_reload、plugin_cleanup_port 可用。
3. 如果需要输入 schema，调用 get_capabilities，传入 toolNames=["plugin_install","plugin_status","plugin_reload","plugin_cleanup_port"] 和 includeSchemas=true。
4. 对上述项目路径调用 plugin_install，overwrite=true。
5. 调用 plugin_status，总结已安装文件、autoload 注册、bridge mode 和 WebSocket 端口。
6. 告诉我在 Godot 编辑器里如何启用插件。
7. 如果需要 runtime 路由，提醒我运行项目后再验证 runtime bridge 状态。
不要修改无关文件。

What It Can Do

Use get_capabilities as the source of truth. The default call returns a lightweight catalog with routeGroup, transport, riskLevel, requiresEditor, requiresRuntime, and canonicalName when a tool is implemented through a shared capability. It does not include input schemas by default. To load schemas, narrow the request with routeGroup, transport, riskLevel, toolNames, or query, then set includeSchemas=true; unfiltered schema requests are rejected to keep the response small.

Core project tools inspect project.godot, list projects, read and update project settings with dry-run support, configure InputMap actions with native Godot syntax, run the project, stop the current run, export configured presets, update Godot 4.4+ UIDs, and run release-friendly project checks. Scene and node tools create/open/save scenes, inspect scene trees, add/delete/rename/duplicate/move nodes, update properties with structured Variant values, manage groups, inspect dependencies, and apply cross-scene edits.

Script, filesystem, and resource tools index GDScript files, read/write scripts, create and attach scripts, run syntax checks, read/write/list/search/delete project files, load/save resources, build dependency graphs, inspect export presets, and preview resource content. Visual workflow tools cover shaders, materials, particles, UI themes/templates, physics bodies and collision layers, navigation regions/agents/meshes, lighting/environment setup, TileMap edits, animation tracks/keyframes, and AnimationTree state machine operations.

Editor tools install and verify the bundled godot-devtool plugin, reload it through the WebSocket bridge, read the live editor selection, select nodes, perform UndoRedo, read/write Inspector properties, and add/delete/rename/move/duplicate nodes in the currently open scene without forcing an external disk reload. The GDT dock shows connection state, the active edited scene, current selection, live-edit availability, save mode, runtime session diagnostics, and the latest command result. Runtime tools work while the game is running: they can read the live scene tree and node properties, set runtime properties, capture screenshots/frames, simulate input actions, inspect UI text/buttons, wait for nodes, navigate agents, monitor properties, record/replay interactions, and run QA-style assertions and stress checks.

Browser visualizer tools start, inspect, and stop a local read-only dashboard. Use browser_visualizer_start to open a http://127.0.0.1:<port>/ page that refreshes bridge status, connected editor/runtime clients, pending command count, and the existing screenshot/scene/input route names to call from the MCP client.

The table below is generated from the actual tool definitions so the README stays aligned with the MCP server.

All 228 Tools

Project Tools (18)

Scene Tools (51)

Node Tools (19)

Script Tools (11)

Editor Tools (16)

Filesystem Tools (11)

Resource Tools (16)

Visual Tools (26)

Runtime Tools (21)

Core Tools (39)

Which Route Should I Use?

• Use native routes for project inspection, file edits, settings, indexes, safety policy, and dependency checks.
• Use headless_godot routes when Godot must load or mutate scenes/resources/scripts correctly.
• Use editor_ws only when the current open editor state matters.
• Use runtime_ws only after the game is running and you need live game state, input, screenshots, or QA assertions.
• Use get_capabilities before automating unfamiliar workflows. Request schemas only for the active route group or exact tools.

Verification

Static and package checks:

npm.cmd run build
npm.cmd run verify:tools
npm.cmd run verify:gdscripts
npm.cmd run verify:plugin
npm.cmd run verify:all

Godot-backed checks require GODOT_PATH:

npm.cmd run verify:runtime
npm.cmd run check:project -- "C:/path/to/your-godot-project"

Troubleshooting

• get_godot_version fails: set GODOT_PATH to the exact Godot executable.
• plugin_status says not installed: run plugin_install for the correct project path.
• Editor routes time out: open the project in Godot and enable the plugin.
• Runtime routes time out: run the game so the DevtoolRuntime autoload can connect.
• Port conflict: change GODOT_DEVTOOL_WS_PORT and reinstall with the same websocketPort.
• MCP client cannot start the server: confirm node is available and build/index.js exists.

Skill

Agent operating guidance is bundled at:

skills/godot-devtool/SKILL.md

Feed this SKILL.md to your AI assistant before asking it to operate on a Godot project. In clients that support file context, attach or reference the file directly; otherwise paste its contents into the chat and tell the AI to follow it when using the godot-devtool MCP server.

The skill maps common Godot operations to the correct MCP tools, teaches assistants to inspect project state first, use stdio/headless routes for repeatable edits, install/use the WebSocket plugin only when live editor or runtime state is required, and validate changes before finishing.