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: