Installation

Add the addon to an existing project, bootstrap a new one, or build from source.

Requirements

Godot 4.7, the version this is developed and released against. 4.3 through 4.8 work in beta.
Go 1.26+ to build the CLI, or a prebuilt release binary.

4.7 is the target, 4.3 is the floor and it is beta

The addon loads and serves on Godot 4.3 through 4.8. Registration is per group, so an engine that cannot compile a group skips it and lists the file under unavailable_groups in engine.commands rather than the plugin failing whole. Six APIs newer than 4.3 refuse with the version they need: scene close needs 4.5, and below 4.7 every close needs --discard because the editor cannot report which tabs hold unsaved work; csg bake and the AGX tonemap need 4.4; runtime error capture needs 4.5, below which runtime errors answers capture: "unavailable" rather than an empty list. The 3.x line is out of scope: run Godot’s own --convert-3to4 first.

Builds this release was run against: the official 4.3.0, 4.4, 4.5, and 4.6 stables, one headless editor per version, each registering all 330 commands with unavailable_groups absent and the game IPC answering; 4.7.1-rc (d6096250e) and 4.7.2-rc (36a04fe52); and a 4.8-dev build from master (eda2a482e, after dev 2). On 4.8 the addon runs unmodified, with every command of that build registering and no parse or compile errors, and engine.search picks up 4.8’s FuzzySearch automatically. Note that 4.8 writes a unique_id attribute into saved scenes which 4.7 does not, so a project saved by 4.8 is not round-trip clean back to 4.7. That is an engine format change, not an addon one.

Moving a project between versions has its own guide: Porting between Godot versions.

Into an existing project

From an unpacked release bundle, install the addon (and the agent skill) into any Godot project in one step:

godot-mcp install --project /path/to/your/project --enable

This copies addons/godot_mcp/ and .claude/skills/godot-mcp/ in and enables the plugin in project.godot, including the two game-side autoloads the runtime and input groups need. Enabling from the editor’s plugin checkbox injects the same pair, so nothing needs pre-committing either way.

Bootstrap a new project

Starting from nothing? Create a fresh Godot 4.7 project and wire the addon in one command:

godot-mcp create --path ./mygame --install --enable

Writes a project.godot (config version 5, 4.7 feature tag), an original placeholder icon.svg, and a .gitignore. It never overwrites an existing project.godot.

Build the CLI from source

go build -o bin/godot-mcp ./cmd/godot-mcp
# or, with Task installed:
task build          # -> bin/godot-mcp(.exe)

Pin the MCP port (per project)

The addon binds the first free port in 9080-9095 and writes it to .godot/godot-mcp.json, so the CLI auto-discovers it and you rarely think about ports. Running two projects at once, pin each to a distinct port so they never contend: Project → Project Settings → Godot Mcp → Network → Port (turn on Advanced Settings to see it). Set an explicit port; 0, the default, means auto-pick.

The value is saved in that project’s project.godot, so two concurrent projects listen deterministically on their own ports. GODOT_MCP_PORT in the environment still overrides everything, and the default 0 is never written to project.godot, so leaving the setting alone keeps the file clean.

Bundled greybox assets (optional)

Copy the bundled CC0 asset packs into a project for prototyping:

godot-mcp install-assets --list
godot-mcp install-assets --pack kenney_prototype_textures

Before you ship

The addon is development tooling and must not ride into an exported game: it is a command server with an arbitrary-eval surface, and its two game-side autoloads poll IPC files every frame, release builds included. Two steps keep it out:

Disable the plugin before exporting (Project → Project Settings → Plugins). Disabling removes the two injected autoloads (MCPGameInspector, MCPGameInput) from project.godot; re-enabling puts them back, so the toggle costs nothing per release.
Exclude the addon files in every export preset. In the Export window, Resources tab, add to Filters to exclude files/folders:
```
addons/godot_mcp/*
```
Add mcp_commands/* too if the project defines project-local commands. The default “Export all resources” mode ships unreferenced scripts, so the filter matters even with the plugin disabled.

Troubleshooting

If the CLI can’t connect, run the environment preflight:

godot-mcp doctor

It checks the godot binary and version, that the project resolves, whether the addon is installed and enabled, the effective port source (env, per-project pin, or auto), whether an editor is actually reachable, and the .NET SDK on C# projects. Pass --project DIR to target a specific project, or --json for machine-readable output. It exits non-zero only when a check fails; a warning (no editor running yet, say) doesn’t fail the run, so doctor is safe to run before you’ve launched anything.

Requirements#

Into an existing project#

Bootstrap a new project#

Build the CLI from source#

Pin the MCP port (per project)#

Bundled greybox assets (optional)#

Before you ship#

Troubleshooting#