godot-mcp

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

📖 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. 194 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.12.

What it is

godot-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

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 — OpenCode (opencode.json in the project root):

{ "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")

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:

• 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.