Godot MCP server

godot-mcp

Give your AI assistant eyes and hands in the Godot editor — and a running game it can actually playtest.

<!-- HERO PLACEHOLDER: short demo GIF goes here (agent running the game, stepping time, reading state). Use an absolute raw.githubusercontent.com URL so it also renders on npm. -->

Why this one?

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:

• Deterministic playtesting. Freeze the game clock, step exact slices of game time (or step until a condition holds), with inputs riding inside the window. Observation never races the game.
• Cheap observation. Live entity state — positions, velocities, animation state, your own custom data — as structured JSON. Most "what's happening on screen?" questions get answered without spending vision tokens on a screenshot.
• Real input. Named actions with analog strength, joypad buttons and stick vectors, raw keys with modifier combos, relative mouse-look, text typing. Sequences run with precise timing and can prove they changed game state.
• Scenario setup. Run GDScript inside the running game: grant the weapon, skip to wave 3, spawn a test bot — no debug hooks baked into your game code.

Here's what that looks like when an agent tests a boss fight:

godot_editor_edit   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_read   screenshot_game           # and a screenshot when it's actually worth the tokens

Less copy-paste, more creating.

Quick Start

1. Configure your AI assistant

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"]
    }
  }
}

2. Install the Godot addon

npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project

Enable it in Godot: Project > Project Settings > Plugins > Godot MCP

3. Start building

Open your Godot project, restart your AI assistant, and start building. If anything refuses to connect, the Troubleshooting Guide has you covered.

What's in the box

21 tools, 86 actions. Full API docs in the Tools Reference.

Shortened. The full README is on GitHub.