Command Palette

Search for a command to run...

UnylyUnyly
Browse all

Godot Editor

FreeNot checked

MCP server that drives a live Godot editor for AI-driven game development

GitHubEmbed

About

MCP server that drives a live Godot editor for AI-driven game development

README

Godot Editor MCP — drive a live Godot editor from an AI agent over MCP

Godot Editor MCP

A generic, game-agnostic Model Context Protocol (MCP) server for AI-driven Godot development.

PyPI Docker Documentation Version Stable MIT License

Make a game? Let your AI assistant install and drive it — For creators. Building on it? Start with the developer track for the contract, architecture, and extension points.

The full manual is hybridindie.github.io/godot-mcp; this README is the front door. For LLM agents: llms.txt (page index) · llms-full.txt (the whole site as one markdown document).

Status: feature-complete. 208 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).

Two channels: stable 2026.10.20.1 (Godot 4.4–4.7, validated on 4.7) and beta 2026.11.04b2, verified against Godot 4.8-beta2 and adding the 4.8-only surface (engine support reporting, scene metadata, physics read-back, VisualShader groups). The floor stays Godot 4.4. Development mirrors the channels: main is the beta line, stable is the stable line (see CONTRIBUTING). godot-editor-mcp on PyPI · ghcr.io/hybridindie/godot-mcp.

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

Why build on this

Godot Editor MCP is meant to be the base you build a game's AI vocabulary on, not one more self-contained assistant. Seven things follow from that:

  • Editor-first, not file-first. Scene and project mutations go through the editor's own APIs, so agent edits join your undo stack (Ctrl+Z) and the editor's save rules apply — not blind file rewrites behind its back. See why & how it works.
  • Safety is enforced on the server. dry_run previews, confirm gates, and preconditions live in the server, not the addon — a misbehaving editor plugin cannot bypass them. See safety classes.
  • A versioned compatibility contract. Tool names, params, result shapes, and a contract_version that additive changes never bump — contract-tested, so an integration does not break silently. See the contract.
  • Ground truth on every mutation. Results report persisted, undoable, aborted_at, and rescan_pending, so a client can tell "looks done" from "is done" without re-reading the scene. See persistence truth.
  • A local extension point. Annotate a typed GDScript function with ## @mcp_tool and it becomes a first-class, safety-classed godot_project_* tool that runs entirely in your editor — no cloud, no fork. See project-defined tools.
  • Skills ship with the server. Three installable skills, including godot-expert (the Godot 4.x rules most people learn by hitting the bug). See skills.
  • No telemetry, no cloud, no client lock-in. MIT, self-hostable, standard MCP — any client, plain config.

Honest comparison against four other live-editor Godot MCP servers (including where this one is not ahead): Comparison with other tools.

Prerequisites

Component Minimum Recommended
Godot 4.4 4.7 stable (validated) · 4.8-beta2 (beta channel)
Python 3.11 3.13
Package manager uv uv

Quick start

1. Install the server

pip install godot-editor-mcp          # stable 2026.10.20.1 (Godot 4.7 validated)
pip install --pre godot-editor-mcp    # beta 2026.11.04b2 (Godot 4.8-beta2)

pip install and uvx godot-editor-mcp resolve the stable release. The beta is opt-in via --pre (PyPI normalizes it to 2026.11.4b2).

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

# stable addon (2026.10.20.1)
curl -L -o godot_mcp_addon.zip \
  https://github.com/hybridindie/godot-mcp/releases/latest/download/godot_mcp_addon.zip

# beta addon (2026.11.04b2) — use the matching server release
curl -L -o godot_mcp_addon.zip \
  https://github.com/hybridindie/godot-mcp/releases/download/2026.11.04b2/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. Install the skills — this is what makes the assistant good at this surface: it learns to enable toolsets on its own, read the result verdicts, and avoid the common Godot pitfalls. Do it before your first session; the server works without them (the instructions and prompts are the fallback), but expect "unknown tool" errors and stale-save mistakes if you skip them:

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.

5. Ask the agent to work — describe the outcome; the assistant picks the toolset, previews, and acts:

  • "Show me the scene tree" → it reads your open scene and tells you what is there.
  • "Add a Player node to the main scene" → it enables scene editing on its own, previews the change, then adds the node to the scene you have open.
  • "Why does it crash on start?" → it runs the scene headlessly and reads the errors back to you.

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. When a task needs more, the assistant enables the toolset itself; 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 its registry. 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
  • Comparison — four other live-editor Godot MCP servers, side by side — including where this one is not ahead
  • 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.

from github.com/hybridindie/godot-mcp

Install Godot Editor in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE
unyly install godot-editor

Installs into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.

First time? Get the CLI: curl -fsSL https://unyly.org/install | sh

Or configure manually

Run in your terminal:

claude mcp add godot-editor -- uvx godot-editor-mcp

Step-by-step: how to install Godot Editor

FAQ

Is Godot Editor MCP free?

Yes, Godot Editor MCP is free — one-click install via Unyly at no cost.

Does Godot Editor need an API key?

No, Godot Editor runs without API keys or environment variables.

Is Godot Editor hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Godot Editor in Claude Desktop, Claude Code or Cursor?

Open Godot Editor on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

Compare Godot Editor with

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All ai MCPs