godot-mcp 0.1.1

MCP server for interfacing with Godot game engine. Provides tools for launching the editor, running projects, and capturing debug output.

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 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
• Python >= 3.10
• uv package manager (includes uvx tool, no extra installation needed)
• An AI assistant that supports MCP (Cline, Cursor, etc.)

What is uvx?

uvx is a tool included with the uv package manager that lets you run Python applications directly from GitHub without cloning the repository or managing virtual environments manually. Once you install uv, the uvx command becomes automatically available.

Benefits of using uvx:

• No need to clone the repository
• Automatically manages dependencies and virtual environments
• Always runs the latest version
• Simplifies the configuration process

Installation

Prerequisites

1. Install Python 3.10 or later
2. Install uv package manager (includes uvx):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   Or follow the uv installation guide

   After installation, you can run uv --version and uvx --version to verify your installation.

Step 1: Run Server

Recommended: Use uvx (No Clone Required)

Recommended Method - Use uvx to run directly from GitHub without cloning:

uvx --from "git+https://github.com/ChanceFlow/godot-mcp@main" godot-mcp

Alternative: Local Development (For Contributing)

Only clone the repository if you plan to contribute or develop locally:

git clone https://github.com/ChanceFlow/godot-mcp.git
cd godot-mcp
uv sync
uv run python godot_mcp/server.py

Step 2: Configure with Your AI Assistant

Recommended: Use uvx

Add to your AI assistant's MCP settings (recommended for most users):

For Cline (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "godot": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ChanceFlow/godot-mcp@main", "godot-mcp"],
      "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"
      ]
    }
  }
}

For Cursor UI:

1. Go to Cursor Settings > Features > MCP
2. Click on + Add New MCP Server button
3. Fill out form:
   • Name: godot (or any name you prefer)
   • Type: command
   • Command: uvx --from "git+https://github.com/ChanceFlow/godot-mcp@main" godot-mcp
4. Click "Add"
5. You may need to press refresh button in top right corner of MCP server card to populate tool list

For Cursor (Project-Specific):

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

{
  "mcpServers": {
    "godot": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ChanceFlow/godot-mcp@main", "godot-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Alternative: Local Development (For Contributing)

Only use this if you've cloned the repository locally:

For Cline:

{
  "mcpServers": {
    "godot": {
      "command": "uv",
      "args": ["run", "python", "godot_mcp/server.py"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

For Cursor: Use uv run python godot_mcp/server.py as the command.

Step 3: Optional Environment Variables

You can customize the server behavior with these 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

Once configured, your AI assistant will automatically run the MCP server when needed. You can 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"

"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.

This architecture provides several benefits:

• No Temporary Files: Eliminates the need for temporary script files, keeping your system clean
• Simplified Codebase: Centralizes all Godot operations in one (somewhat) organized file
• Better Maintainability: Makes it easier to add new operations or modify existing ones
• Improved Error Handling: Provides consistent error reporting across all operations
• Reduced Overhead: Minimizes file I/O operations for better performance

The bundled script accepts operation type and parameters as JSON, allowing for flexible and dynamic operation execution without generating temporary files for each operation.

Development

Running the Server

Direct execution:

uv run python godot_mcp/server.py

Development mode with MCP Inspector:

uv run mcp dev godot_mcp/server.py

Testing

Run tests with pytest:

pytest

Troubleshooting

• Godot Not Found: Set the GODOT_PATH environment variable to your Godot executable
• 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
• Python Version: Ensure you're using Python 3.10 or later

License

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