Theatre

Appearance

MCP Toolkit for Godot

Your AI can read your code.
Now it can see — and act in — your game.

Theatre gives AI agents spatial awareness of running Godot games, live interaction for testing hypotheses, and the ability to build scenes, resources, and animations — all through the Model Context Protocol.

Get StartedLearn More

The Problem ​

AI coding agents can read your source files, set breakpoints, inspect variables — but they cannot see your game. When an enemy clips through a wall, when a patrol path overshoots, when physics bodies tunnel through geometry — your agent has no way to observe these problems.

It's like debugging a web app without being able to open the browser.

Two Tools, One Stage ​

🎭

Stage

See and interact with the running game. Spatial snapshots, real-time deltas, watches, recordings — plus live property mutation and method calls for testing hypotheses without restarting.

9 MCP tools~200–3000 tokens
🎬

Director

Build and modify scenes, resources, tilemaps, and animations through Godot's own API. No hand-editing .tscn files.

38+ operations~50–500 tokens

How It Works ​

AI Agent(Claude Code, Cursor, etc.)
Stage (MCP)
observe & interact
Director (MCP)
build the game
stage server
director server
TCP :9077
TCP :6551/:6550
Godot GDExtension(running)
Godot GDScript(editor)

Theatre connects your AI agent to your Godot game through the Model Context Protocol (MCP). Stage observes and interacts with the running game via a GDExtension addon. Director modifies scenes through the editor or headless Godot. Both communicate over TCP, exposing structured tools your agent already knows how to use.

The Dashcam Moment ​

The killer workflow: human plays, AI analyzes.

I just recorded a clip of the bug. The player clips through the east wall around frame 340.
Let me analyze the recording around that frame.
Found it. At frame 337, the player velocity spikes to 45 units/frame — the CharacterBody3D tunnels through the wall collision shape. The move_and_slide delta is too large for the CollisionShape3D thickness (0.3 units). Two fixes: thicken the collision shape to 1.0, or enable continuous collision detection.

You press F9 to mark the bug moment — the dashcam saves the last 60 seconds of spatial data — and the agent scrubs through the spatial timeline to find exactly what went wrong — no screenshots, no narration, no guessing from code.

Real Debugging Scenarios ​

💥

Physics Tunneling

Fast-moving objects pass through walls. The code looks right but the collision just... doesn't happen.

See how to debug this →
🗺️

Pathfinding Failures

NPCs get stuck, take bizarre routes, or refuse to move. The navmesh looks fine in the editor.

See how to debug this →
🎭

Collision Layer Confusion

Two objects should collide but don't. Or they collide when they shouldn't. Layer/mask bits are a maze.

See how to debug this →
🎵

Animation Sync Issues

The attack animation plays but the hitbox doesn't activate at the right frame. Timing is off.

See how to debug this →

Quick Start ​

1. Install Theatre ​

bash
curl -LsSf https://github.com/nklisch/theatre/releases/latest/download/install.sh | sh

Or build from source.

2. Set up your Godot project ​

bash
theatre init ~/your-godot-project

This copies addons, generates .mcp.json, and enables plugins — all interactively.

3. Install agent skills (optional) ​

bash
skilltap install nklisch/theatre

Install skilltap to manage agent skills. Installs theatre-stage (spatial debugging) and theatre-director (scene authoring) skills that teach your agent tool selection, workflows, and pitfalls.

4. Run your game and ask ​

"Take a spatial snapshot of my scene"

Your AI agent now sees your game world — via MCP tools or CLI (stage spatial_snapshot '{"detail":"summary"}'). Ask it to set a property or call a method on a running node to test a fix without restarting.