godot-mcp · sandraschi — Claude Code MCP server: what it does, how to install
An MCP server for controlling Godot 4 through natural language and tooling. It assists with GDScript logic creation, scene editing, and deterministic frame-by-frame playtesting.
Open on GitHubWhat godot-mcp does
The server connects an AI coding agent to Godot 4 over a TCP bridge. It enables direct scene tree manipulation, direct TileMap cell editing, and 3D asset imports for OBJ, STL, or GLB files. The built-in Game Builder pipeline handles GDScript generation, passes the code through gdlint and Godot compile checks, and prompts the language model to fix syntax issues.
Deterministic playtesting is a core capability. The agent freezes the engine clock, injects simulated gamepad or mouse inputs, and steps forward frame-by-frame until a target condition triggers. Live node properties return as structured JSON via the _mcp_state() hook. The built-in profiler monitors 14 engine metrics and flags performance spikes.
Running the bridge requires Godot 4.4 or newer, Python 3.13, Bun, and the uv package manager. Without Godot installed locally, the server cannot interact with any game project. An Ollama instance running gemma4:12b can also be attached for offline game logic generation.
What it helps with
- inspect and modify Godot 4 scene nodes over a TCP bridge
- run deterministic playtests with frame stepping and simulated inputs
- generate validated GDScript files with automated
gdlintsyntax repairs - import 3D meshes in STL, GLB, and OBJ formats along with Gaussian splats
- track engine performance spikes across 14 runtime metrics
Example prompts for the agent
- Create a procedural checkerboard texture using
godot_generate_procedural_texturefor the floor material. - Step through the game frame-by-frame, inject jump inputs, and read the state with
godot_state_digest. - Build a 2D runner prototype with
just gb-demoand validate the GDScript logic.
How to install godot-mcp
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about godot-mcp
How do I install and run godot-mcp for Claude Code?
Clone the repository with git clone https://github.com/sandraschi/godot-mcp, enter the directory using cd godot-mcp, install dependencies with just bootstrap, and launch the server using just serve.
What does godot-mcp do?
It connects an AI coding assistant to the Godot 4 engine. It enables automated GDScript authoring, scene and mesh management, deterministic frame stepping, and runtime performance profiling.
What are the prerequisites for running godot-mcp?
The server requires Godot 4.4+, Python 3.13+ paired with uv, and bun. An Ollama setup with gemma4:12b is optional if you want local code generation.
Similar MCP servers
All MCP servers for Game dev and 3D: Unity, Unreal, Godot, Blender →godot-mcp by other authors comes first.
