Godot MCP

What @yanhuifair/godot-mcp does

@yanhuifair/godot-mcp exposes Godot Engine 4.x project operations through the Model Context Protocol. Its tools cover native project-file handling for .tscn scenes, .tres resources, GDScript, C#, .gdshader files, and project.godot. These file operations use parsers and can run without an open Godot process.

The server also provides live editor and runtime functions when its Godot plugin is enabled. AI clients can manage nodes, signals, shaders, lightmap baking, breakpoints, debugging, game execution, and editor state. Runtime tools can inspect the live scene tree, invoke methods, inject input, freeze execution, advance one frame, and capture screenshots.

How it works

The package runs as an MCP server that an AI client starts, commonly through npx. A project path points the server at the directory containing project.godot. The client communicates with the server over stdio, SSE, or streamable HTTP, depending on the selected transport.

The optional editor plugin bridges the server to a running Godot editor and game. Scene mutations performed through the editor are registered with Godot's native undo system, allowing them to be reverted with the normal undo command. get_status reports connection state, while search_tools helps locate capabilities across the large tool catalog.

Setup and configuration

Godot 4.x and Node.js 18 or newer are required. Godot 3 is not supported. To install and enable the project plugin, run the package from the project directory:

npx @yanhuifair/godot-mcp --enable-plugin -p .

The path must resolve to the folder containing project.godot; an absolute path can be supplied instead. This places the plugin under addons/godot-mcp/ and enables it in the project settings. Reload an already-open Godot project after installation.

A stdio client configuration can start the server with:

{
  "mcpServers": {
    "godot-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@yanhuifair/godot-mcp", "-p", "."]
    }
  }
}

Restart the AI client after changing its MCP configuration. Run get_status to check the connection and available bridges.

Tools and capabilities

• Read and modify Godot scenes, resources, scripts, shaders, and project settings.
• Add, remove, rename, move, reparent, duplicate, and instantiate scene nodes with undo support.
• Control editor playback, selection, signals, breakpoints, debugging, viewport actions, and lightmap baking.
• Inspect running-game scene trees and call methods on live objects.
• Inject input, pause or freeze runtime execution, step by frame, and take screenshots.
• Discover tools with search_tools and inspect connectivity with get_status.

Limitations and notes

Live editor and running-game features require the Godot plugin and a reachable Godot editor. More than 220 file-oriented tools can operate without the plugin or an open Godot process, but they do not provide live editor or runtime access. The project must use Godot 4.x, and the configured project path must contain project.godot.