# godot-mcp

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 6
- Author: sandraschi
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/sandraschi/godot-mcp
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/sandraschi-godot-mcp

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Works with: Godot

## Install

### Claude Code (native platform)

**Install**
- The MCP registry has no launch command for it: see the repository README

## When to use it
- 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 `gdlint` syntax repairs
- import 3D meshes in STL, GLB, and OBJ formats along with Gaussian splats
- track engine performance spikes across 14 runtime metrics

## Example prompts
- Create a procedural checkerboard texture using `godot_generate_procedural_texture` for 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-demo` and validate the GDScript logic.

## Similar
- [Pascal 3D Editor](https://affpapa.org/en/nevibecode/mcp/pascal-3d-editor.md) — MCP server · ★ 25137
- [Unity-MCP](https://affpapa.org/en/nevibecode/mcp/unity-mcp.md) — MCP server · ★ 4534
- [mcp](https://affpapa.org/en/nevibecode/mcp/sceneview-mcp.md) — MCP server · ★ 1349
- [Gearboy MCP Server](https://affpapa.org/en/nevibecode/mcp/gearboy-mcp-server.md) — MCP server · ★ 1218
- [ChiR24-unreal_mcp_server](https://affpapa.org/en/nevibecode/mcp/chir24-unreal-mcp-server.md) — MCP server · ★ 982
- [Nova3D](https://affpapa.org/en/nevibecode/mcp/nova3d.md) — MCP server · ★ 732

## Other versions with the same name
- [godot-mcp · tomyud1](https://affpapa.org/en/nevibecode/mcp/tomyud1-godot-mcp.md) — ★ 445

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md