Give your AI assistant eyes and hands in the Godot editor: scene editing, input injection, deterministic playtesting, and live game state for agents
# Add to your Claude Code skills
git clone https://github.com/satelliteoflove/godot-mcpLast scanned: 6/12/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-06-12T08:26:33.382Z",
"npmAuditRan": true,
"pipAuditRan": true,
"promptInjectionRan": true
}No comments yet. Be the first to share your thoughts!
30 days in the Featured rail · terms & refunds
Give your AI assistant eyes and hands in the Godot editor — and a running game it can actually playtest.
There are a few Godot MCP servers out there, and most can open a scene and poke at nodes. This one is built around a harder problem: letting an agent verify its own work. Run the game, drive it like a player, observe what actually happened, and prove the change did what it claimed — without you ferrying screenshots and error logs back and forth.
The pieces that make that possible, and that you won't find elsewhere:
Here's what that looks like when an agent tests a boss fight:
godot_editor run frozen=true # boot with game time frozen at frame 0
godot_exec GameState.wave = 3 # set up the scenario worth testing
godot_game_time step_until "tree.get_nodes_in_group('boss').size() >= 1"
godot_runtime_state digest # exact positions and state — no pixels, no guessing
godot_game_time step 500ms + dodge input # play the moment that matters
godot_editor screenshot_game # and a screenshot when it's actually worth the tokens
Less copy-paste, more creating.
Add godot-mcp to your MCP client. See the Installation Guide for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more). The short version:
{
"mcpServers": {
"godot-mcp": {
"command": "npx",
"args": ["-y", "@satelliteoflove/godot-mcp"]
}
}
}
npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project
Enable it in Godot: Project > Project Settings > Plugins > Godot MCP
Open your Godot project, restart your AI assistant, and start building. If anything refuses to connect, the Troubleshooting Guide has you covered.
15 tools, ~90 actions, 3 MCP resources. Full API docs in the Tools Reference.
| Tool | What it does |
|---|---|
godot_scene |
Open, save, and create scenes |
godot_node |
Create, update, delete, and reparent nodes; attach scripts; connect signals |
godot_editor |
Editor state, selection, run/stop/restart, screenshots, editor error log, 2D viewport control |
godot_project |
Project info and settings |
godot_animation |
Query, play, and edit animations down to individual tracks and keyframes |
godot_tilemap / godot_gridmap |
Read and edit TileMapLayer and GridMap cells |
godot_resource |
Inspect resources with type-aware output: SpriteFrames, TileSet, Materials, Textures |
godot_scene3d |
3D transforms, bounding boxes, and visibility for spatial reasoning |
godot_docs |
Fetch Godot documentation as clean markdown, version-matched to your editor |
godot_input |
Inject input into the running game: actions, joypad, raw keys, mouse-look, text |
godot_profiler |
Metric snapshots and per-frame time series with spike detection |
godot_runtime_state |
Live game state as JSON: one-shot digests, watch windows, signal timelines |
godot_game_time |
Freeze, step, and step-until on the game clock — deterministic observation |
godot_exec |
Run GDScript inside the running game for test scenario setup |
A note on shape: this kit deliberately stays at 15 tools rather than 90. Related operations live as actions inside one tool, so your agent's context isn't flooded with tool definitions it won't use.
A feel for what an agent can do with this, in plain prompts:
For richer runtime observation, add key nodes to the mcp_watch group or give them a _mcp_state() method — see the Runtime State Guide.
┌─────────────────┐ stdio ┌─────────────────┐ WebSocket ┌──────────────────┐ debugger ┌──────────────┐
│ MCP client │ ◄────────► │ godot-mcp │ ◄──────────► │ Bridge addon │ ◄─────────► │ Running game │
│ (Claude, etc.) │ │ server (Node) │ :6550 │ (Godot editor) │ wire │ (autoload) │
└─────────────────┘ └─────────────────┘ └──────────────────┘ └──────────────┘
The server talks to an editor addon over a local WebSocket; the addon reaches into the running game over Godot's own debugger protocol, so the game process needs no extra ports or setup. The addon binds to 127.0.0.1 by default. WSL2 is fully supported (auto-detection, host IP discovery, configurable bind modes) — see the Installation Guide.
Curious about connection lifecycles, the single-client policy, or how frozen-time stepping works under the hood? The Architecture Guide goes deep.
minimal-godot-mcp by @ryanmazzolini covers exactly what this server doesn't: LSP diagnostics for fast static GDScript checking, and the running game's console output over DAP. This server covers everything that needs an editor bridge. No overlap, no conflict — run both, and your agent gets static analysis and the game console alongside full editor and runtime control.
One caveat: a Godot editor serves a single godot-mcp client at a time. Extra clients (a subagent inheriting your MCP config, say) wait their turn rather than hijacking your session — details in Troubleshooting.
mcp_watch and _mcp_state()cd server
npm install && npm run build
npm test
npm run generate-docs
Contributions welcome — this project favors tools that solve real, time-wasting problems. Read CONTRIBUTING.md before building something big, or open an issue and we'll figure out the right shape together.