Summary

This repository provides godot-mcp, a comprehensive Model Context Protocol (MCP) server designed to grant AI assistants full programmatic control over the Godot game engine. It addresses the need for deep integration between AI development tools and game development workflows, enabling AI-driven game creation and iteration. The project targets AI developers and game developers seeking to leverage AI for tasks ranging from project management and scene manipulation to runtime control and debugging, offering a significant expansion over its foundational predecessor.

How It Works

The system employs a dual-channel architecture for interacting with Godot projects. For operations that do not require a running game instance, such as scene file parsing, modification, or resource creation, a headless CLI approach is used. This involves running Godot in headless mode with a dedicated GDScript runner (godot_operations.gd). For runtime control of a live game, a TCP socket-based communication channel is established. An autoload script (mcp_interaction_server.gd) within the Godot project listens on 127.0.0.1:9090, processing JSON commands sent by the TypeScript MCP server. This separation allows for both static project manipulation and dynamic in-game control.

Quick Start & Requirements

• Installation:
  1. git clone https://github.com/tugcantopaloglu/godot-mcp.git
  2. cd godot-mcp
  3. npm install
  4. npm run build
• Prerequisites:
  • Godot Engine (4.x recommended; 4.4+ required for UID features)
  • Node.js >= 18.0.0
  • An AI assistant supporting MCP (e.g., Claude Code, Cline, Cursor).
• Runtime Setup: Copy build/scripts/mcp_interaction_server.gd to your Godot project's scripts folder and register it as an autoload named McpInteractionServer.
• Configuration: Specific JSON configurations are provided for integrating with Claude Code, Cline, and Cursor MCP clients.
• Environment Variables: GODOT_PATH (optional, path to Godot executable), DEBUG (optional, enables server-side logging).
• Documentation: Configuration examples and tool descriptions are available within the README.

Highlighted Details

• Expands functionality from the original project to 149 distinct tools.
• Supports runtime GDScript code execution (game_eval) with full await support, even when the game is paused.
• Enables deep runtime node inspection and manipulation, including property access, method calls, scene instantiation, and reparenting.
• Offers headless scene operations for reading, modifying, and creating resources directly from .tscn and .tres files without running the game.
• Provides extensive project management capabilities, including settings modification, file I/O, and project creation.
• Features robust support for networking (HTTP, WebSocket, ENet multiplayer), 3D/2D rendering, physics, animation control, and UI manipulation.
• Includes advanced robustness features like reentrancy guards, comprehensive type conversion for Godot data structures, and graceful error handling.

Maintenance & Community

The project is an extension of the godot-mcp by Solomon Elias (Coding-Solo), with significant contributions by Tugcan Topaloglu. No specific community links (e.g., Discord, Slack) or roadmap details are provided in the README.

Licensing & Compatibility

This project is released under the MIT License, which permits broad use, modification, and distribution, including for commercial purposes and integration into closed-source projects.

Limitations & Caveats

Certain features, specifically those related to updating Unique IDs (UIDs) for resources, require Godot version 4.4 or later. The effectiveness of the runtime tools is dependent on the correct setup of the McpInteractionServer autoload within the Godot project. Integration relies on the user's AI assistant supporting the MCP protocol.