Godot MCP

What the Godot MCP MCP server does

The Godot MCP MCP server gives an MCP client access to a Godot editor project and its running game. It is intended for agent-assisted development and verification, especially when a change needs to be exercised in gameplay rather than inspected only in source files.

The server exposes 21 tools with 86 actions. These cover scene and node operations, editor state, screenshots, project information, animations, tilemap and gridmap cells, resources, 3D scene data, Godot documentation, input, profiling, runtime state, game-time control, GDScript execution, and procedural mesh validation.

For the 🎮 Gaming category, useful workflows include reproducing a collision problem, checking an animation during play, collecting entity positions and velocities, profiling frame spikes, or preparing a test scenario by running GDScript inside the game.

How it works

An MCP client communicates with the Node-based server over stdio. The server connects to the Godot editor addon over a local WebSocket, normally bound to 127.0.0.1. The addon communicates with the running game through Godot’s debugger protocol, so the game does not need an additional listening port.

Game-time controls can freeze execution, advance by an exact duration, or continue until a condition is met. Inputs can be included in timed steps, allowing an agent to compare a known action sequence with structured runtime observations. Runtime state is returned as JSON and can include positions, velocities, animation information, and custom data from watched nodes or _mcp_state() methods.

The editor accepts one godot-mcp client at a time. Additional clients wait rather than taking over the active session. WSL2 is supported with automatic detection, host IP discovery, and configurable binding modes.

Setup and configuration

The Godot MCP MCP server requires Node 20 or newer and Godot 4.5 or newer. Add it to an MCP client with a stdio configuration such as:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@satelliteoflove/godot-mcp"]
    }
  }
}

Install the Godot addon into the target project with:

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

Enable the addon under Project > Project Settings > Plugins > Godot MCP, then open the project and restart the MCP client. A --read-only option is available for workflows that should inspect without modifying project state.

Tools and capabilities

• Open and save scenes, inspect scene trees, find nodes, update properties, and reparent nodes.
• Read and author animations, tracks, and keyframes with editor preview.
• Inspect or edit TileMapLayer and GridMap cells, including encoded scene data.
• Read editor state, selections, screenshots, errors, and 2D viewport controls.
• Inject named actions, analog input, joypad controls, keyboard combinations, mouse-look movement, and text.
• Freeze or advance game time and wait for runtime conditions.
• Read live runtime state, watch windows, and signal timelines as JSON.
• Run GDScript for scenario setup, such as spawning a test object or changing game progress.
• Capture profiler metrics and time series, and detect spikes.

The Godot MCP MCP server intentionally does not duplicate file-based operations such as creating nodes or attaching scripts when those can be performed directly by editing project files.

Limitations and notes

The Godot MCP MCP server depends on both the Node process and the Godot editor addon being available. Its bridge is focused on editor state, runtime verification, encoded cell data, and game control. Static GDScript diagnostics and running-game console output are outside its stated scope; the README identifies minimal-godot-mcp as a complementary server for those functions.

A single Godot editor supports one active client session. Read-only tools can be auto-allowed separately from write operations, but actions that change the editor, project, or running game should remain appropriately gated.