dcc-mcp-godot

Use Godot with AI agents

Install the official DCC-MCP Agent Skill. Codex users can use the native plugin
marketplace:

codex plugin marketplace add dcc-mcp/dcc-mcp-agent-plugins
codex plugin add dcc-mcp@dcc-mcp

For Claude Code, CodeBuddy, Cursor, Gemini CLI, and other supported agents, use
the official installation guide. Start Godot,
enable this adapter, and verify that the running instance is registered:

dcc-mcp-cli list

Then ask your agent:

Use dcc-mcp to inspect the current Godot project.

The list must include dcc_type=godot. If it does not, follow the
connection troubleshooting guide.

Part of the DCC-MCP host matrix

dcc-mcp-godot — Godot Engine adapter and game-authoring skills for DCC-MCP.

It is one of 48 host adapters in the DCC-MCP catalog. Every adapter speaks the same
MCP protocol and builds on the same core runtime contract; each one exposes the tools
its own host needs on top of that.

• All host adapters and install metadata
• Host matrix on the core README
• Showcase

This block is generated from the catalog entry in
dcc-mcp-catalog.yml.
Re-run the generator after changing the catalog.

For embedded controllers, see Server configuration.
For imported PNG assignment to UI nodes, see UI textures.
For offscreen scene rendering, its inputs and outputs, and the per-platform support
matrix, see Scene previews.

Agent workflow

AI agents should use the shared gateway through dcc-mcp-cli; IDE users may
continue to use the MCP endpoint. Prefer typed skills and tools over raw scripts.

Install or update the CLI

dcc-mcp-cli is the preferred control path for every shell-capable agent. If
it is missing, ask the user before installing the latest official release:

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/dcc-mcp/dcc-mcp-core/main/scripts/install-cli.ps1 | iex"

Keep an official build current through the release manifest:

dcc-mcp-cli update check
dcc-mcp-cli update apply

update apply downloads and stages the latest CLI for the next launch. It
does not update a running dcc-mcp-server; update that server in its own
environment.

dcc-mcp-cli dcc-types
dcc-mcp-cli list
dcc-mcp-cli search --query "<task>" --dcc-type godot
dcc-mcp-cli describe <tool-slug>
dcc-mcp-cli call <tool-slug> --json '{"key":"value"}'

dcc-types reports release-catalog support; list reports live sessions. If a
tool belongs to an inactive progressive skill, call dcc-mcp-cli load-skill <skill-name> --dcc-type godot before retrying. For post-task improvement,
attach a stable session id with --meta-json, query dcc-mcp-cli stats --range 24h --session-id <task-id>, then pass the bounded evidence to the
review_skill_improvement prompt from dcc-mcp-skills-creator.

For release packaging, load godot-build-optimization after choosing the
target export preset. It scans the project, generates a version-aware
custom.py and optional .gdbuild profile in a staging directory, and records
artifact sizes and SHA-256 digests. Generated disable flags remain hypotheses
until the packaged build is launched and smoke-tested.

Godot 4 editor adapter for the DCC Model Context Protocol ecosystem. It ships a GDScript
EditorPlugin, an EngineDebugger runtime peer, 177 skill-qualified tool entries, and a tested 2D
arena-roguelike skill.

Install

The canonical agent-first, three-platform lifecycle is documented in
install.md. It provides plan-first JSON, staged project updates,
receipts, repair, live verification, upgrade, and receipt-owned uninstall.

pip install dcc-mcp-godot
dcc-mcp-godot install /path/to/project --dcc-path /path/to/godot --dry-run --json
dcc-mcp-godot install /path/to/project --dcc-path /path/to/godot --yes --json

The legacy install-only alias remains compatible:

dcc-mcp-godot-install /path/to/project

When using only that legacy alias, enable DCC-MCP Godot under Project
Settings > Plugins. Start the adapter with either compatible form:

dcc-mcp-godot
dcc-mcp-godot serve

Each adapter instance uses an OS-assigned MCP port and registers it for CLI discovery.
Connect through the stable gateway at http://127.0.0.1:9765/mcp; set
DCC_MCP_GODOT_PORT only when a fixed direct endpoint is required. The plugin connects
to the loopback bridge at ws://127.0.0.1:3847; override the bridge port with
DCC_MCP_GODOT_BRIDGE_PORT before starting both processes.

For embedded controllers, see Server configuration.
For imported PNG assignment to UI nodes, see UI textures.
For offscreen scene rendering, its inputs and outputs, and the per-platform support
matrix, see Scene previews.

Agent workflow

1. Search skills for the required domain, such as Godot animation, Godot runtime, or
   Godot TileMap.
2. Load only the returned domain skill. Tools remain deferred until their skill is loaded.
3. Inspect the project or scene before mutating it, then save and validate the result.
4. Load godot-runtime, godot-input, or godot-testing-qa after starting the game when
   live inspection, input simulation, or QA assertions are required.

The original godot-project, godot-scene, and godot-roguelike skills remain available.

Capability skills

The adapter groups 166 fine-grained tools into 23 independently loadable domains:

Runtime tools use the official EditorDebuggerPlugin and EngineDebugger channel, so input
events and game-node operations run in the game process rather than the editor process. Enabling
the plugin registers the bundled runtime peer as an autoload; disabling it removes the autoload.

Scene edits use Godot's undo manager and file operations are restricted to res:// with size and
extension checks. execute_editor_script only calls a method on an existing @tool project
script. The compatibility tool execute_game_script is not an allowlist: it is a broad public-method
call on an existing runtime node. It must not be used for playtest or RL control, and neither broad
tool accepts raw source for immediate evaluation.

For bounded playtest control, use execute_typed_action. It accepts only the strict
input_action and exact script-digest-bound set_property variants declared in the fixed
res://.dcc-mcp/playtest-actions.v1.json project manifest. Calls bind the project, session,
process-unique redacted runtime ID, authority, manifest ID, and manifest SHA-256; replacement,
identity drift, reparse points, extra fields, exhausted budgets, and rate limits fail closed.
The host verifies the exact setter effect and script digest on both sides of mutation. Rejected or
cancelled actions do not consume authority; a cancelled or orphaned claimed mutation is rolled
back before its reservation expires. The editor forwards a typed mutation only after an exact
request-digest authorization handshake; a timeout that wins before authorization leaves a
terminal fence, so a delayed WebSocket commit is rejected before reaching the runtime.
Read Typed playtest actions before enabling this path. This foundation
does not provide episodes, rewards, trajectories, NPC control, an RL trainer, or another recorder.

Main-thread work budgets

get_game_scene_tree, get_game_node_properties, and find_ui_elements accept opaque cursor
values returned as next_cursor. Their max_nodes or max_properties limits are clamped to 128,
and the default page is 64 items. Each read reports its measured elapsed_ms, requested/clamped
budget_ms (1–50, default 40), and budget_exceeded. When the budget is exhausted the response
is an incomplete page; continue with the returned cursor and never infer a complete snapshot. Do
not construct or retain a second host-side job. Legacy calls without a cursor still return the
original top-level fields, plus the first bounded page and continuation metadata.

get_game_screenshot reads the viewport and copies its RGB8/RGBA8 bytes on the Godot runtime
thread. The existing adapter execution thread then encodes and atomically replaces the requested
PNG; include_base64=true also encodes that PNG there. No Godot Image resource crosses threads.

get_editor_screenshot and capture_frames use the same immutable raw-pixel handoff; PNG encoding
is never performed on the editor or game thread. capture_frames may return fewer frames than
requested when its budget is exhausted; resume with start_index=next_index.

Unattended scene rendering

render_scene_preview renders a .tscn/.scn offscreen and returns {path, width, height, bytes} plus rendering_method and unique_colors, so a caller can check which backend produced
the frame and that it carries real shading. Both are diagnostics, not proof: they rule out a blank
frame or a foreign backend, not a frame that renders the wrong scene.

The host must be windowed. Under --headless Godot degrades to rendering/dummy, where an
offscreen SubViewport reads back nothing; the tool refuses instead of returning a blank PNG that
looks like success. To run without a visible window, launch the host through the unattended
launcher, which starts a windowed editor and, on Windows, places the whole process on a private
desktop so nothing appears on the interactive desktop:

dcc-mcp-godot unattended --godot /path/to/godot --project /path/to/project --timeout 300 --json

Off Windows the launcher reports mode=plain: the host still renders, but its window is part of
the current desktop. Ask for a rendering_method that is not the one actually active and the tool
errors instead of silently rendering on another backend — cross-renderer frames differ enough to
invalidate any comparison baseline. Never hide the host by minimizing: under gl_compatibility a
minimized window reports success while rendering an entirely black frame.

Pixels are staged raw by the host and encoded by the adapter, so the PNG encode stays off the
Godot thread.

Support is per platform, and every row is either measured or explicitly not measured:
windowed, hidden-window and private-desktop runs are measured on Windows; the Xvfb lane is
measured on Linux; macOS has no host and is unmeasured; a host with no logon session is
unmeasured everywhere. "Unattended" never means headless — see the full matrix, the acceptance
tiers and the measured noise floors in Scene previews.

execute_editor_script accepts budget_ms from 1 to 50 and reports elapsed_ms plus
budget_exceeded; this is an observational contract and cannot preempt GDScript. With
chunked=true, the existing method must return {done: bool, next_cursor?: value}. An incomplete
chunk returns a machine-executable next_step that calls the same path and method with the next
cursor. The adapter does not add a script executor, timer, thread, or job registry.

Real Godot CI

CI resolves the official godotengine/godot latest stable GitHub release and downloads the Linux
editor (reusing the existing cache when present). It starts the packaged MCP server and EditorPlugin, sends real JSON-RPC load_skill,
paginated tools/list, tools/call, and jobs_get_status requests, creates and edits a scene,
starts the game, verifies the runtime scene tree, then runs the generated gameplay simulation and
requires ROGUELIKE_SMOKE_OK.

Run the same smoke locally:

python tools/download_latest_godot.py --output .godot-bin
python tests/live_godot_smoke.py --godot /path/to/Godot

Development

python -m pip install -e ".[dev]"
pytest
ruff check src tests tools
ruff format --check src tests tools
python tools/lint_skills.py
python -m build
python -m twine check dist/*