# Godot MCP Enhanced

[![MCP Server](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)
[![Node.js](https://img.shields.io/badge/Node.js-339933?style=flat&logo=nodedotjs&logoColor=white 'Node.js')](https://nodejs.org/en/download/)
[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white 'TypeScript')](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-red.svg 'MIT License')](https://opensource.org/licenses/MIT)

An enhanced Model Context Protocol (MCP) server for interacting with the Godot game engine. This server enables AI assistants to launch the Godot editor, run projects, manage scenes and nodes, handle scripts, and much more.

## Features

### Project Management
- **Launch Godot Editor**: Open the Godot editor for a specific project
- **Run Godot Projects**: Execute Godot projects in debug mode with output capture
- **Capture Debug Output**: Retrieve console output and error messages in real-time
- **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 Scenes**: Create new scenes with specified root node types
- **Add Nodes**: Add nodes to existing scenes with customizable properties
- **Load Sprites**: Load textures into Sprite2D nodes
- **Save Scenes**: Save scenes with options for creating variants

### Script Management
- **Create Scripts**: Generate GDScript files with various templates:
  - Empty template
  - Node2D/Node3D/Control templates
  - CharacterBody2D/CharacterBody3D with movement code
- **Attach Scripts**: Attach scripts to nodes in scenes

### UID Management (Godot 4.4+)
- **Get UID**: Retrieve the unique identifier for specific files
- **Update Project UIDs**: Resave resources to update UID references

### Export Operations
- **Export Mesh Library**: Export 3D scenes as MeshLibrary resources for GridMap

## Requirements

- [Godot Engine](https://godotengine.org/download) 4.x installed on your system
- Node.js (>=18.0.0) and npm
- An MCP-compatible AI assistant (Claude, Cline, Cursor, etc.)

## Installation

### Quick Start with Claude Code

```bash
claude mcp add godot -- npx @xinyuzjj/godot-mcp
```

With environment variables:

```bash
claude mcp add godot -e GODOT_PATH=/path/to/godot -e DEBUG=true -- npx @xinyuzjj/godot-mcp
```

### Cline

Add to your Cline MCP settings file:

```json
{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@xinyuzjj/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",
        "save_scene",
        "create_script",
        "attach_script",
        "get_uid",
        "update_project_uids",
        "export_mesh_library"
      ]
    }
  }
}
```

### 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:
   - Name: `godot`
   - Type: `command`
   - Command: `npx @xinyuzjj/godot-mcp`
4. Click "Add"
5. You may need to press the refresh button to populate the tool list

**Using Project-Specific Configuration:**

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

```json
{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@xinyuzjj/godot-mcp"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}
```

### Other MCP Clients

For any MCP-compatible client, use this configuration:

```json
{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["@xinyuzjj/godot-mcp"],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "DEBUG": "true"
      }
    }
  }
}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `GODOT_PATH` | Path to the Godot executable (overrides automatic detection) |
| `DEBUG` | Set to `"true"` to enable detailed server-side debug logging |

## Building from Source

```bash
git clone https://github.com/xinyuzjj/godot-mcp.git
cd godot-mcp
npm install
npm run build
```

Then point your MCP client to `build/index.js` instead of using `npx`.

## 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 comprehensive GDScript file (`godot_operations.gd`) that handles all operations.

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

## Available Tools

| Tool | Description |
|------|-------------|
| `launch_editor` | Launch Godot editor for a specific project |
| `run_project` | Run the Godot project and capture output |
| `get_debug_output` | Get the current debug output and errors |
| `stop_project` | Stop the currently running Godot project |
| `get_godot_version` | Get the installed Godot version |
| `list_projects` | List Godot projects in a directory |
| `get_project_info` | Retrieve metadata about a Godot project |
| `create_scene` | Create a new Godot scene file |
| `add_node` | Add a node to an existing scene |
| `load_sprite` | Load a sprite into a Sprite2D node |
| `save_scene` | Save changes to a scene file |
| `create_script` | Create a new GDScript file |
| `attach_script` | Attach a script to a node in a scene |
| `get_uid` | Get the UID for a specific file (Godot 4.4+) |
| `update_project_uids` | Update UID references in a project (Godot 4.4+) |
| `export_mesh_library` | Export a scene as a MeshLibrary resource |

## Supported Node Types

The server supports creating the following node types:

- **Basic**: Node, Node2D, Node3D, Control
- **Physics**: CharacterBody2D, CharacterBody3D, RigidBody2D, RigidBody3D, StaticBody2D, StaticBody3D, Area2D, Area3D
- **Visual**: Sprite2D, Sprite3D, AnimatedSprite2D, Camera2D, Camera3D
- **UI**: Label, Button, Panel, ColorRect, TextureRect, ProgressBar
- **Audio**: AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D
- **Animation**: AnimationPlayer, AnimationTree
- **Collision**: CollisionShape2D, CollisionShape3D
- **Navigation**: NavigationRegion2D, NavigationRegion3D, NavigationAgent2D, NavigationAgent3D
- **Lighting**: PointLight2D, DirectionalLight2D, DirectionalLight3D, OmniLight3D, SpotLight3D
- **And many more...**

## Troubleshooting

- **Godot Not Found**: Set the `GODOT_PATH` environment variable to your Godot executable path
- **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**: Make sure all dependencies are installed by running `npm install`

### Cursor-Specific Issues

- Ensure the MCP server shows up and is enabled in Cursor settings (Settings > MCP)
- MCP tools can only be run using the Agent chat profile (Cursor Pro or Business subscription)
- Use "Yolo Mode" to automatically run MCP tool requests

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Inspired by the original [Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp) project
- Built with the [Model Context Protocol](https://modelcontextprotocol.io/)
- Powered by [Godot Engine](https://godotengine.org/)