📌Overview

Purpose: Godot MCP is designed to facilitate interaction with the Godot game engine through a standardized interface for AI assistants, allowing for enhanced project management and debugging.

Overview: Godot MCP enables AI assistants to effectively launch the Godot editor, execute projects, capture debug outputs, and manage project execution, ultimately improving the development workflow and code generation.

Key Features:

• Launch Godot Editor: Opens the Godot editor for specific projects, allowing seamless project management and access.

• Run Godot Projects: Executes projects in debug mode, providing real-time feedback on project performance.

• Capture Debug Output: Retrieves console output and error messages, assisting in the debugging process.

• Control Execution: Offers programmatic control to start and stop Godot projects, enabling automated workflows.

• Scene Management: Enhances scene creation and modification capabilities, supporting complex project structures with options for adding nodes and exporting resources.

• UID Management: For Godot 4.4+, manages unique identifiers for resources, simplifying project upgrades and resource handling.

---

Godot MCP

A Model Context Protocol (MCP) server for interacting with the Godot game engine.

Introduction

Godot MCP enables AI assistants to launch the Godot editor, run projects, capture debug output, and control project execution through a standardized interface. This feedback loop helps improve code generation and debugging assistance.

Features

• Launch Godot Editor: Open the Godot editor for a specific project.
• Run Godot Projects: Execute projects in debug mode.
• Capture Debug Output: Retrieve console output and error messages.
• Control Execution: Start and stop projects programmatically.
• Get Godot Version: Retrieve the installed Godot version.
• List Godot Projects: Find projects in a specified directory.
• Project Analysis: Get detailed information about project structure.
• Scene Management:
  • Create new scenes with specified root node types.
  • Add nodes to existing scenes with customizable properties.
  • Load sprites and textures into Sprite2D nodes.
  • Export 3D scenes as MeshLibrary resources for GridMap.
  • Save scenes with options for creating variants.
• UID Management (for Godot 4.4+):
  • Get UID for specific files.
  • Update UID references by resaving resources.

Requirements

• Godot Engine installed on your system.
• Node.js and npm.
• An AI assistant that supports MCP (e.g., Cline, Cursor).

Installation and Configuration

Step 1: Install and Build

Clone the repository and build the MCP server:

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

Step 2: Configure with Your AI Assistant

Option A: Configure with Cline

Add to your Cline MCP settings file:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

Option B: Configure with Cursor

Using the Cursor UI:

1. Go to Cursor Settings > Features > MCP.
2. Click on the + Add New MCP Server button.
3. Fill out the form and click "Add".
4. Refresh the MCP server card to populate the tool list.

Using Project-Specific Configuration:

Create a file at .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  
      }
    }
  }
}

Step 3: Optional Environment Variables

Customize the server behavior with these environment variables:

• GODOT_PATH: Path to the Godot executable.
• DEBUG: Set to "true" for detailed server-side debug logging.

Example Prompts

Once configured, use prompts like:

• "Launch the Godot editor for my project at /path/to/project"
• "Run my Godot project and show me any errors"
• "Get information about my Godot project structure"
• "Analyze my Godot project structure and suggest improvements"
• "Help me debug this error in my Godot project: [paste error]"

Implementation Details

Architecture

The Godot MCP server uses a bundled GDScript approach for complex operations, enhancing maintainability and performance while providing consistent error handling.

Troubleshooting

• Godot Not Found: Set the GODOT_PATH environment variable.
• Connection Issues: Ensure the server is running and restart your AI assistant.
• Invalid Project Path: Ensure the path points to a directory containing a project.godot file.
• Build Issues: Ensure all dependencies are installed by running npm install.

License

This project is licensed under the MIT License - see the LICENSE file for details.