Godot Editor MCP

📖 The manual is the docs site: hybridindie.github.io/godot-mcp. This README is the front door — what it is, install, quick start, and links. Architecture, guides, and the full tool reference live on the site.

For LLM agents: llms.txt (page index) · llms-full.txt (the whole site as one markdown document).

Status: feature-complete. 201 tools across 29 categories — always-on core plus 28 toggleable toolsets, of which only inspection is enabled by default (the rest are gated off until the agent asks). godot-editor-mcp on PyPI · ghcr.io/hybridindie/godot-mcp · version 2026.10.24.

Project-defined tools (new in 2026.10.24): annotate a typed GDScript function with ## @mcp_tool and register it as a godot_project_* tool — guide.

One name, three identifiers. Godot Editor MCP is the product: it drives the editor as its surface, through the addon. The repository and MCP server ID stay godot-mcp for wire compatibility; the package/CLI is godot-editor-mcp; the in-editor plugin is Godot Editor MCP - Addon; and every tool shares the godot_ prefix.

---

What it is

Godot Editor MCP bridges an AI agent and a live Godot editor. Instead of editing files blindly on disk, the agent drives the editor directly over MCP:

• Inspect the scene tree, selected nodes, and project settings live
• Mutate scenes — nodes, scripts, signals — with undo
• Edit GDScript and check it for parse errors
• Run the game headless or control a live play session
• Simulate input, record replays, screenshot, and profile performance
• Export builds, analyze code statically, and refactor across scenes

It is game-agnostic — it knows Godot, not your game. A tower-defense roguelite, a 3D platformer, and a visual novel use the same generic tools; game-specific vocabulary belongs in a separate consumer project.

AI client ──stdio / HTTP──▶ FastMCP server ──WebSocket──▶ Godot addon ──▶ live editor

Prerequisites

Component	Minimum	Recommended
Godot	4.4	4.7 (validated target)
Python	3.11	3.13
Package manager	uv	uv

Quick start

1. Install the server

pip install godot-editor-mcp      # or run without installing: uvx godot-editor-mcp

2. Install the Godot addon into your project, then enable it in Project → Project Settings → Plugins → Godot Editor MCP - Addon:

curl -L -o godot_mcp_addon.zip \
  https://github.com/hybridindie/godot-mcp/releases/latest/download/godot_mcp_addon.zip
unzip godot_mcp_addon.zip -d /path/to/your/project/

(Or install Godot Editor MCP - Addon from the Godot Asset Store.) A status dock appears in the editor; the addon connects out to the server's bridge (ws://127.0.0.1:9080 by default) and reconnects automatically, so editor and server can start in either order.

3. Point your MCP client at it — generate the config, or write the OpenCode entry by hand:

godot-editor-mcp config --client opencode --write
godot-editor-mcp config --client cursor --project /path/to/project --write
godot-editor-mcp doctor --project /path/to/project   # checklist + a fix for every failure

{ "mcp": { "godot": { "type": "local", "command": ["uvx", "godot-editor-mcp"] } } }

4. Ask the agent to work

• "Show me the scene tree" → godot_inspection_get_scene_tree()
• "Enable scene editing, then add a Player node" → godot_enable_toolset("scene_edit")

5. (Recommended) Install the skills — paste this into your assistant so it learns how to drive the editor (enable toolsets on its own, read the result verdicts, and avoid the common Godot pitfalls). The server works without them — the instructions and prompts are the fallback — but they make it noticeably better:

Install the Godot Editor MCP AI skills into your skills directory: clone or download
https://github.com/hybridindie/godot-mcp and copy the three folders under its `skills/`
directory (godot-getting-started, godot-playtest-and-debug, godot-expert) into your
skills directory — keep godot-expert/references/ — then reload your skills.

More → Skills.

Docker, HTTP service mode (several clients sharing one editor), and OpenWebUI → Configure your client.

The gated surface

Only core + inspection are exposed by default, so the agent's tool list stays sharp. It turns a toolset on with godot_enable_toolset("scene_edit"); the server then announces the change (tools/list_changed, plus a subscriptions/listen stream on the 2026-07-28 protocol) and returns the enabled tools' schemas — so the new tools reach the model whether or not its client refreshes. GODOT_MCP_DEFAULT_TOOLSETS pre-seeds toolsets at startup. More → Toolset gating.

Documentation

The full manual lives on the docs site:

• For creators — make a game by talking to your AI assistant
• For developers — integrate, extend, or contribute to the server
• Get started — install, connect, and drive your first session
• Concepts — how it works and why it's built this way
• Guides — build a scene, play-test & debug, verify, ship
• Reference — toolsets, safety, errors, prompts, skills, env vars
• Under the hood — the bridge, gating, safety, persistence, readiness
• Changelog — what shipped in each release

Development

uv sync
uv run pytest           # full suite
uv run ruff check .     # lint
uv run mypy             # types

The Godot addon lives at godot/addons/godot_mcp/; open the godot/ folder as a project to load it.

Contributing & license

See CONTRIBUTING.md. MIT licensed — see LICENSE.