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. The stdio MCP server starts without binding the WebSocket bridge port; bridge tools open the local bridge on demand, keep it alive while run_project is active or a runtime client is connected, and otherwise release the port after tool-call cleanup.

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.
• The local WebSocket listener is a shared broker, so multiple MCP clients or AI agents can use the same bridge port instead of each spawning an exclusive listener.
• Editor and runtime sessions are identified by projectPath, context, sessionId, and runId; ambiguous live targets return candidates instead of guessing.
• run_project creates tracked run instances. Use list_run_instances, get_debug_output, stop_project, and stop_run_instance with runId when multiple game instances are active.
• get_capabilities supports focused workflow filters such as project_setup, live_editor, runtime_test, multi_instance, and release_verify to keep assistant context small.
• tools/list is router-only: it exposes only entry tools plus tool category metadata, with no cursor pagination or environment-variable mode switch. Load full tool input schemas through filtered get_capabilities calls.

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.

Codex And Claude Plugin Bundle

The repository is also packaged like an IDE plugin bundle for agentic coding tools:

• plugin.json exposes the shared plugin metadata, agents/, and skills/.
• .codex-plugin/plugin.json exposes Codex marketplace/interface metadata.
• .claude-plugin/plugin.json exposes Claude Code plugin metadata.
• agents/godot-dev.agent.md is the user-invocable godot-dev Agent. It routes work through skills/godot-devtool/SKILL.md and the focused workflow skills.

npm run build copies these manifests, the Agent, and all Skills into build/ so a release zip contains the MCP server plus the IDE-style guidance layer.

Install From Local Build

1. Build from source, or extract a published release zip to a stable path. The release asset name for this version is godot-devtool-build-3.2.0.zip.

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

2. Confirm the server entry exists:

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

3. 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" }
   

4. 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. The stdio MCP server starts without opening that port. Bridge tools open it on demand; editor-only calls release it during cleanup, while a project launched through run_project or an already connected runtime client keeps the listener open so runtime commands do not depend on a one-call reconnect window. If another godot-devtool process already owns the same port, broker-aware calls can forward through that listener instead of killing it.

If another listener already holds the port while a bridge tool runs, use plugin_status and plugin_cleanup_port to inspect it. Only call plugin_cleanup_port with kill=true after confirming the listener is stale; switching ports creates a separate bridge and does not adopt editor clients connected to the old one.

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 MCP tools/list response is a context-budget-safe router surface: it exposes only get_capabilities, get_godot_version, and list_projects, plus _meta.toolCategories summaries for route groups, workflows, transports, and risk levels. It does not support cursor pagination and does not provide an environment-variable switch back to full-schema tools/list. The default get_capabilities 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 full input schemas, narrow the request with workflow, 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 235 Tools

Project Tools (18)

Scene Tools (51)

Node Tools (17)

Script Tools (11)

Editor Tools (17)

Filesystem Tools (11)

Resource Tools (16)

Visual Tools (25)

Runtime Tools (30)

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 workflow, route group, or exact tools; do not rely on tools/list for full schemas.

Verification

Static and package checks:

npx.cmd tsc --noEmit
npm.cmd run build
npm.cmd run verify:tools
npm.cmd run verify:gdscripts
npm.cmd run verify:visualizer
npm.cmd run verify:plugin

Full release checks require GODOT_PATH and a local Godot runtime:

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

After a development branch passes the required verification gates, merge it into main before treating the branch as complete.

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: inspect the owner with plugin_cleanup_port; stop only a verified stale listener, or deliberately set a matching alternate 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.