Godot MCP: An MCP Server for AI Agent Control of the Godot Game Engine

What Godot MCP Does and Why It Exists

AI coding agents can generate Godot scripts and scene configurations, but without a way to run the project and observe the output, the agent has no feedback on whether the code actually works in Godot. Godot MCP creates that feedback loop by exposing Godot engine operations as MCP tools that an agent can call directly from a shell.

The README explains the motivation: "This direct feedback loop helps agents understand what works and what doesn't in real Godot projects, leading to better code generation and debugging assistance." In practice, an agent can write a GDScript file, call the MCP server to run the project, retrieve the debug output, identify an error, and correct the script, all within a single agent session.

The tool is built on the Model Context Protocol, an open standard for giving language models access to structured tools, and it works with any MCP-compatible agent including Claude Code, Cursor, VS Code, OpenCode, OpenClaw, Codex and Gemini CLI, as listed in the README.

Tools Provided: Launch, Run, Scene Management and UID Handling

The README lists the available MCP tools by category. Execution tools include launching the Godot editor for a project, running a project in debug mode, capturing debug console output, stopping a running project, retrieving the installed Godot version, and listing Godot projects in a specified directory.

Project analysis provides information about project structure. Scene management tools cover creating new scenes with a specified root node type, adding nodes to existing scenes with customizable properties, loading sprites and textures into Sprite2D nodes, exporting 3D scenes as MeshLibrary resources for use with GridMap, and saving scenes with options for creating variants.

For Godot 4.4 and above, UID management tools address a specific change in that engine version: getting the UID for a specific file, and updating UID references by resaving resources. This matters because Godot 4.4 introduced UID-based resource references that can break if files are moved without updating references.

Installing Godot MCP in Claude Code, Cursor and VS Code

For Claude Code, the README gives a single command:

claude mcp add godot -- npx @coding-solo/godot-mcp

Restart Claude Code and the Godot tools are available. With environment variable overrides:

claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx @coding-solo/godot-mcp

For Cursor, using the UI: go to Cursor Settings, then Features, then MCP, and click Add New MCP Server. The command is `npx @coding-solo/godot-mcp`. For a project-specific configuration, create `.cursor/mcp.json`:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@coding-solo/godot-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

For other MCP-compatible clients, the same JSON configuration structure applies. The `GODOT_PATH` environment variable overrides automatic detection of the Godot executable. Setting `DEBUG` to `"true"` enables detailed server-side logging. Node.js 18.0.0 or higher is required.

For building from source:

git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp
npm install
npm run build

How the Architecture Handles Simple and Complex Operations

The README documents a two-path architecture. Simple operations, such as launching the editor or querying project information, call Godot's built-in command-line interface directly. No intermediate scripts are involved.

Complex operations, such as creating scenes, adding nodes or loading sprites, use a bundled GDScript file called `godot_operations.gd`. This script accepts an operation type and parameters as JSON, executes the corresponding operation within Godot, and returns the result. The README explains the design choice: using a single comprehensive script avoids generating temporary files for each operation, which would clutter the project directory and create cleanup overhead.

This architecture means the tool does not generate and inject GDScript ad hoc. The GDScript logic for supported operations is fixed in the bundled file, which keeps behavior predictable but also means operations not covered by that file require a source modification.

Requirements and Common Troubleshooting Points

Godot MCP requires Godot Engine installed on the system, Node.js 18.0.0 or above, npm, and an MCP-compatible agent. The package.json lists the Godot executable detected automatically; the `GODOT_PATH` variable overrides this for non-standard install locations.

The README lists specific troubleshooting cases. If Godot is not found, set `GODOT_PATH`. For connection issues, restart the AI assistant after confirming the server is running. If the project path is invalid, the directory must contain a `project.godot` file. Build issues require running `npm install` first.

For Cursor users, the README notes that MCP tools require the Agent chat profile, which is available on Cursor Pro or Business subscriptions. "Yolo Mode" in Cursor automatically approves MCP tool requests instead of asking for confirmation on each call.

What Godot MCP Does Not Cover

Godot MCP provides the tools listed in the README, but it does not cover every Godot editor operation. Scene manipulation is limited to the operations in the bundled `godot_operations.gd` script: creating scenes, adding nodes, loading sprites into Sprite2D nodes, exporting MeshLibraries and saving scenes. Operations outside this set, such as shader management, animation editing, physics layer configuration or export template management, are not available as MCP tools.

The tool also does not interact with the Godot Asset Library or with version control systems. Asset downloading, project import from version control, and dependency management are outside its scope.

For projects that require the agent to modify many different aspects of the Godot project, the agent will need to fall back to direct file editing for the operations Godot MCP does not expose, which reduces the value of the run-and-observe feedback loop for those specific operations.

Licence, Maintenance and Comparison with Direct CLI Use

Godot MCP is MIT-licensed, which permits commercial and personal use, modification and redistribution without restrictions. The package is published to npm as `@coding-solo/godot-mcp` at version 0.1.1 according to package.json.

The last push to the repository was on 2026-04-16. The project does not have GitHub releases; the version is tracked in package.json. Active users should verify the current npm version against the repository before deploying in a team environment.

The direct alternative to Godot MCP is using the Godot command-line interface directly in agent shell calls. The Godot CLI supports running projects with `godot --headless` and similar flags. Godot MCP adds the scene manipulation and UID management tools on top of CLI equivalents, and abstracts the output parsing so the agent receives structured results rather than raw stdout. For agents that only need to run a project and capture output, the raw CLI is sufficient; for those that need to create or modify scenes programmatically, the MCP toolset reduces the amount of GDScript the agent must write and execute.

Editorial conclusion

Godot MCP is worth installing if you use an AI agent for Godot development and want it to run, observe and iterate on your project in a real Godot instance rather than generating code blindly. The single-command install via npx makes the setup cost low. The last push was on 2026-04-16, so the project has not received updates in about five months at the time of this writing; verify that the tool list covers your specific workflow before committing to it. For Godot 4.4+ users, the UID management tools address a pain point specific to that version. The MIT licence permits use in any context without restrictions.

Frequently asked questions

Official sources

1. Coding-Solo/godot-mcp on GitHub
2. Issues
3. License: MIT
4. README