# Godot MCP

[![Github-sponsors](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=#EA4AAA)](https://github.com/sponsors/Coding-Solo)

[![](https://badge.mcpx.dev?type=server 'MCP Server')](https://modelcontextprotocol.io/introduction)
[![Made with Godot](https://img.shields.io/badge/Made%20with-Godot-478CBF?style=flat&logo=godot%20engine&logoColor=white)](https://godotengine.org)
[![](https://img.shields.io/badge/Python-3.10%2B-blue?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![](https://img.shields.io/badge/vim-0A0197A?style=flat&logo=vim&logoColor=white)](https://www.vim.org/)

[![](https://img.shields.io/github/last-commit/Coding-Solo/godot-mcp 'Last Commit')](https://github.com/Coding-Solo/godot-mcp/commits/main)
[![](https://img.shields.io/github/stars/Coding-Solo/godot-mcp 'Stars')](https://github.com/Coding-Solo/godot-mcp/stargazers)
[![](https://img.shields.io/github/forks/Coding-Solo/godot-mcp 'Forks')](https://github.com/Coding-Solo/godot-mcp/network/members)
[![](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)

[![中文文档](https://img.shields.io/badge/文档-中文-red.svg)](README.zh-CN.md)

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](https://godotengine.org/download) installed on your system
- [Python](https://www.python.org/downloads/) >= 3.10
- [uv](https://docs.astral.sh/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):
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
   Or follow the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation)
   >
   > 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:

```bash
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:

```bash
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`):

```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:

```json
{
  "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:**

```json
{
  "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:

```text
"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:
```bash
uv run python godot_mcp/server.py
```

Development mode with MCP Inspector:
```bash
uv run mcp dev godot_mcp/server.py
```

### Testing

Run tests with pytest:
```bash
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](LICENSE) file for details.