godot-devtool

# godot-devtool

English | 中文

godot-devtool is a Godot 4 MCP server for AI-assisted project inspection, editing, validation, and runtime automation. Version 2.6.0 adds a local Browser visualizer for WebSocket bridge status, connected editor/runtime clients, and live-route guidance.

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, 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.6.0.zip

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

   Expand-Archive ".\godot-devtool-build-2.6.0.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"
         }
       }
     }
   }
   

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

   get_godot_version
   get_capabilities
   

GODOT_DEVTOOL_WS_PORT defaults to 8766. Change it only if that port is already in use.

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.
2. Confirm plugin_install, plugin_status, and plugin_reload are available.
3. Call plugin_install with overwrite=true for the project path above.
4. Call plugin_status and summarize installed files, autoload registration, bridge mode, and WebSocket port.
5. Tell me exactly how to enable the plugin in Godot.
6. 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 可用。
3. 对上述项目路径调用 plugin_install，overwrite=true。
4. 调用 plugin_status，总结已安装文件、autoload 注册、bridge mode 和 WebSocket 端口。
5. 告诉我在 Godot 编辑器里如何启用插件。
6. 如果需要 runtime 路由，提醒我运行项目后再验证 runtime bridge 状态。
不要修改无关文件。

What It Can Do

Use get_capabilities as the source of truth. Every tool reports routeGroup, transport, riskLevel, requiresEditor, requiresRuntime, and canonicalName when a tool is implemented through a shared capability.

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, and read/write Inspector properties. 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 220 Tools

Project Tools (18)

Scene Tools (51)

Node Tools (18)

Script Tools (11)

Editor Tools (9)

Filesystem Tools (11)

Resource Tools (16)

Visual Tools (26)

Runtime Tools (20)

Core Tools (40)

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.

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 -- "E:/test"

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

The skill teaches assistants to inspect project state first, choose the right route group, install/use the WebSocket plugin only when live editor or runtime state is required, and validate changes before finishing.