Godot MCP Server

Godot MCP (Model Context Protocol)

Project Overview

Godot MCP provides a comprehensive, production-ready integration between Large Language Models (LLMs) and the Godot Engine (versions 4.x). It creates a unified Model Context Protocol interface allowing AI assistants to intelligently read, write, and manipulate Godot project files, interact with the live Godot Editor, and perform End-to-End (E2E) testing on running games. By consolidating multiple AI-to-Godot features into a single robust toolkit, Godot MCP dramatically lowers the friction of AI-assisted game development.

Installation & Usage

1. Prerequisites

• Node.js (v18 or higher)
• Godot Engine 4.x
• Supported MCP client (e.g., Claude Desktop)

2. Add the Godot Plugin

Navigate to your specific Godot project's root folder in your terminal and run:

npx -y @xianlee/godot-mcp install

This will automatically copy the addons/godot_mcp folder into your project. Enable the godot_mcp plugin via Project > Project Settings > Plugins in the Godot Editor.

3. Configure the MCP Client (Claude Desktop Example)

Add the following configuration to your mcp config json:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["-y", "@xianlee/godot-mcp"],
      "env": {
        "GODOT_PATH": "<OPTIONAL_ABSOLUTE_PATH_TO_GODOT_EXECUTABLE>"
      }
    }
  }
}

4. Running the Complete Toolchain

1. Ensure your Godot editor is open with the godot_mcp plugin enabled.
2. Start your MCP Client (like Claude Desktop). The server will download on-the-fly and seamlessly jump into the Godot WebSocket.

Feature List

• Live Editor Manipulation: Modify nodes, properties, and scenes in real-time within the Godot Editor.
• Deep Project Context: Read and analyze scripts, scene structures (.tscn), and project files dynamically.
• Version-Aware Godot Docs: Automatically query Godot documentation matching your specific engine version.
• End-to-End Game Bridge testing: Play, test, and assert logic in live running games via simulated inputs and state queries.
• Advanced Diagnostics: View diagnostics, validate scenes, and debug live errors automatically.
• Consolidated Architecture: Minimal tool footprint heavily utilizing action parameters to conserve AI context windows.
• Auto-Screenshot Loop: Periodically captures visual screenshots of the editor or running game state to provide AI with continuous visual context.
• Bug Fix Loop: Automatically collects stack traces from the Godot engine, analyzes runtime errors, and iteratively proposes code fixes.
• Scene Tree Viewer: Interactive web-based visualizer for inspecting the live Godot scene tree and node properties via a browser.
• Intelligent Path Detection: Seamlessly detects correct Godot project paths and environment variables, even when loaded via external IDEs.
• Robust Connection Handling: Enterprise-grade WebSocket connections featuring command queuing, exponential backoff, and large payload buffering.
• Universal Asset Resolution: Resolves internal Godot UUIDs (uid://... or .uid files) dynamically to absolute file paths, ensuring seamless AI context mapping.

MCP Tools Reference