Installation

Requirements#

• Godot 4.7.
• Go 1.26+ to build the CLI, or a prebuilt release binary.

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. The addon self-installs its game-side autoloads on enable, so the runtime and input groups work without pre-committing anything.

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

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 — for C# projects — the .NET SDK. Pass --project DIR to target a specific project, or --json for machine-readable output. It exits non-zero only when a check truly fails; a warning (no editor running yet, say) doesn’t fail the run, so doctor is safe to run before you’ve launched anything.