Godot MCP is a Model Context Protocol (MCP) server paired with a Godot editor addon, so an AI assistant can inspect and edit a Godot project and drive the game while it runs. The server speaks stdio to the MCP client and reaches the editor addon over a local WebSocket. The addon in turn reaches the running game over Godot's own debugger protocol, so the game process needs no extra ports or setup.
The design centers on letting an agent check its own work rather than relying on someone to relay screenshots and error logs. Game time can be frozen at frame 0, stepped in exact slices, or stepped until a condition holds, with input dispatched inside that window so observation never races the game. Live entity state (positions, velocities, animation state, and any data a node exposes through the mcpwatch group or a mcp_state() method) comes back as structured JSON, which answers most "what is happening on screen" questions without a screenshot. GDScript can be run inside the running game to set up a scenario, so a test does not need debug hooks baked into the game code.
The surface is 21 tools and 86 actions, split along the read/write boundary so every _read tool can be auto-allowed in a client's permission settings while writes stay gated. A --read-only flag covers the look-but-don't-touch case. Related operations stay grouped as actions inside one tool to keep tool definitions out of the agent's context, and anything an agent could do by editing project files directly (creating scenes and nodes, attaching scripts, connecting signals) is deliberately not duplicated. A Godot editor serves one client at a time, and WSL2 is supported with auto-detection and configurable bind modes.
Features
- Deterministic playtesting: godotgametime freezes, steps, and steps-until on the game clock so observation is repeatable
- Runtime state: godotruntimestate returns one-shot digests, watch windows, and signal timelines as JSON
- Input injection: godot_input sends named actions with analog strength, joypad buttons and sticks, raw keys with modifiers, mouse-look, and typed text
- Scenario setup: godot_exec runs GDScript inside the running game to grant items, skip levels, or spawn test objects
- Scene and node work: open and save scenes, inspect effective properties and the full tree including instanced sub-scenes, update properties, and reparent
- Editor control: editor state, selection, screenshots, the editor error log, run/stop/restart, and 2D viewport control
- Animation authoring: query animations down to keyframes and author tracks and keyframes with instant editor preview
- Tilemap and gridmap editing: read and write TileMapLayer and GridMap cells that are base64-encoded in the scene file
- 3D reasoning: engine-computed transforms, bounding boxes, and visibility through godot_scene3d
- Profiling: metric snapshots and per-frame time series with spike detection
- Documentation lookup: godot_docs fetches Godot documentation as Markdown, version-matched to the editor
- Mesh validation: detects silently corrupt procedural mesh data that presents as a lighting bug
