Godot MCP

Godot MCP

AI-driven Godot 4 control via MCP — scene manipulation, 3D import, GPU particles, procedural textures, HTML5 export. Deterministic playtesting: freeze the game clock, inject analog/joypad/mouse input, step frame-by-step until a condition is met, read live game state as structured JSON. Game Builder: describe a game in natural language and get playable GDScript + export. Publish to itch.io and Steam. 95+ tools, 77 tests, NSIS desktop installer.

---

Quick Install

git clone https://github.com/sandraschi/godot-mcp

cd godot-mcp just bootstrap # install deps just serve # start server (10993) just web # open dashboard (10992)

See INSTALL.md for all options (MCPB, dev setup, naked PC).

---

Start Here: Game Builder (prompt to playable game)

New here? This is the showpiece. Describe a game in one sentence and get back a structured GamePlan (worlds, scenes, scripts, mechanics), Marble 3D worlds, a composed Godot 4.4 scene, validated GDScript, and an HTML5 export ready for itch.io. Precursor to our standalone gamecraft repo.

just gb-demo "A 2D runner where you collect stars and avoid spikes"

• Open the dashboard: Game Builder page (/game-builder) — 6-step pipeline viz (Design, Worlds, Compose, Logic, Export, Ship).
• Walkthrough: Game Builder Tutorial — prompt to game, end to end.
• Help tab in the webapp (/help — Game Builder section) lists every tool with copy-paste examples.
• Needs Ollama for LLM planning (ollama pull gemma4:12b), worldlabs-mcp :10865 for Marble worlds (optional), Godot bridge :9080 for scene import.

Next generation: [gamecraft](../gamecraft) is our new champion game

builder and depot. It takes a sentence, validates the plan, compiles a real

Godot 4 project folder, boots Godot headless, and verifies the game can

actually be finished. godot-mcp Game Builder is the in-dashboard precursor;

gamecraft is where new builder work lands.

---

Features

• Game Builder — design_game -> generate_game_logic -> generate_game_tests -> generate_dialogue -> export. Validated with gdlint + godot --check-only, auto-repaired by LLM. Tutorial
• Procedural textures — godot_generate_procedural_texture: gradient, noise, checker, solid. No external assets needed.
• Deterministic playtesting — freeze game clock, step frame-by-step, step-until GDScript condition, analog/joypad/mouse/text input injection. Three-phase implementation inspired by satelliteoflove/godot-mcp.
• Structured game state — godot_state_digest reads live node state as JSON via _mcp_state() convention or auto-collected properties. Cheaper than full scene tree dump.
• Engine control — 30 bridge tools: import STL/GLB/OBJ, particles, cameras, lighting, animation, viewport capture, input simulation, scene node management.
• Animation keyframe editor — query tracks down to individual keyframes, insert/remove keys, set interpolation.
• TileMap/GridMap editing — read and write cell data directly (bypasses base64 .tscn serialization).
• Performance profiler — 14 engine metrics with auto-sampling and spike detection (>2 stddev).
• Mesh validation — scan for NaN vertices, degenerate triangles, zero normals.
• 3D Gaussian Splat import — import .ply and .spz files with a custom billboarded Gaussian shader (per-splat scale, SH DC color).
• Publishing — itch_ops and steam_ops portmanteaus for itch.io Butler and SteamPipe. Cross-repo fleet pipeline.
• GDScript validation — two-pass (gdlint style + godot compile) with LLM repair.
• Plugin ecosystem — 7 community plugins installable from the /plugins page.
• LLM detection — auto GPU probe, model recommendation by VRAM tier. Default gemma4:12b.
• Sample game — Vibecoder Runner with 10 AI-themed enemy types.

What You Can Do

just gb-demo "A 2D runner where you collect stars and avoid spikes"

just bridge-test # check engine connection just demo-run vibecode # play sample game just gb-preview # preview latest HTML5 export

Documentation

Requirements

• Godot 4.4+ (for engine bridge tools) — just install-godot or godotengine.org
• Python 3.13+ + uv — winget install astral-sh.uv
• Bun — winget install oven-sh.bun
• Ollama (optional, for game builder) — winget install Ollama.Ollama then ollama pull gemma4:12b
• Rust (optional, for NSIS build) — rustup.rs

License

MIT — see LICENSE.