📌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 — all through a standardized interface.

This direct feedback loop helps AI assistants like Claude understand what works and what doesn't in real Godot projects, leading to better code generation and debugging assistance.

Features

• Launch Godot Editor: Open the Godot editor for a specific project
• Run Godot Projects: Execute Godot projects in debug mode
• Capture Debug Output: Retrieve console output and error messages
• Control Execution: Start and stop Godot projects programmatically
• Get Godot Version: Retrieve the installed Godot version
• List Godot Projects: Find Godot 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: https://godotengine.org/download
• Node.js and npm
• An AI assistant that supports MCP (Cline, Cursor, etc.)

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 (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "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 the "+ Add New MCP Server" button
3. Fill out the form:
   • Name: godot (or any name you prefer)
   • Type: command
   • Command: node /absolute/path/to/godot-mcp/build/index.js
4. Click "Add"
5. Press the refresh button on 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 environment variables:

• GODOT_PATH: Path to the Godot executable (overrides automatic detection)
• DEBUG: Set to "true" to enable detailed server-side debug logging

Example Prompts

Your AI assistant can use prompts such as:

• 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]
• Write a GDScript for a character controller with double jump and wall sliding
• Create a new scene with a Player node in my Godot project
• Add a Sprite2D node to my player scene and load the character texture
• Export my 3D models as a MeshLibrary for use with GridMap
• Create a UI scene with buttons and labels for my game's main menu
• Get the UID for a specific script file in my Godot 4.4 project
• Update UID references in my Godot project after upgrading to 4.4

Implementation Details

Architecture

The Godot MCP server uses a bundled GDScript approach for complex operations:

1. Direct Commands: Simple operations like launching the editor or getting project info use Godot's built-in CLI commands directly.
2. Bundled Operations Script: Complex operations like creating scenes or adding nodes use a single comprehensive GDScript file (godot_operations.gd) that handles all operations.

Benefits include:

• No temporary files, keeping the system clean
• Centralized Godot operations in one organized file
• Easier to add or modify operations
• Consistent error reporting
• Reduced file I/O overhead for better performance

Operations and parameters are passed as JSON to the script for flexibility.

Troubleshooting

• Godot Not Found: Set the GODOT_PATH environment variable to your Godot executable
• Connection Issues: Ensure the server is running; restart your AI assistant if necessary
• Invalid Project Path: Ensure the path contains a project.godot file
• Build Issues: Run npm install to ensure dependencies are installed
• Cursor Specific:
  • Ensure the MCP server is enabled in Cursor settings
  • MCP tools require running with the Agent chat profile (Cursor Pro or Business subscription)
  • Use "Yolo Mode" to automatically run MCP tool requests

License

This project is licensed under the MIT License.