# Godot AI MCP Server

An enhanced Model Context Protocol (MCP) server for the Godot game engine. Provides AI assistants with tools to launch the editor, run projects, manipulate scenes, manage scripts, and control node properties — all through a standardized MCP interface.

> **Based on** [`@coding-solo/godot-mcp`](https://github.com/Coding-Solo/godot-mcp) by [Solomon Elias](https://github.com/Coding-Solo). That project provides the original core tools (launch editor, run project, scene management, UID tools). This fork adds script manipulation (`set_script`, `read_script`, `write_script`, `list_scripts`), scene inspection (`get_scene_tree`), node removal (`remove_node`), and property editing (`set_node_property`).

Original project: **[Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp)** — MIT License.

## Features

### Core Tools
- **launch_editor** — Open the Godot editor for a project
- **run_project** — Run a Godot project in debug mode
- **get_debug_output** — Capture stdout/stderr from running projects
- **stop_project** — Stop a running project
- **get_godot_version** — Check installed Godot version
- **list_projects** — Find Godot projects in a directory
- **get_project_info** — Get project metadata (scene count, script count, etc.)

### Scene Management
- **create_scene** — Create new scene files with any root node type
- **add_node** — Add nodes to existing scenes with properties
- **remove_node** — Remove nodes from scenes
- **get_scene_tree** — Inspect the full scene tree structure
- **load_sprite** — Load textures into Sprite2D/Sprite3D/TextureRect nodes
- **export_mesh_library** — Export 3D scenes as MeshLibrary for GridMap
- **save_scene** — Save/repack scene files

### Script Tools
- **set_script** — Attach a script to a node (creates the script if it doesn't exist)
- **read_script** — Read `.gd`, `.cs`, or `.shader` file contents
- **write_script** — Create or overwrite script files
- **list_scripts** — List all scripts in a project

### Node Properties
- **set_node_property** — Set any property on a node in a scene

### UID Management (Godot 4.4+)
- **get_uid** — Get UID for a specific file
- **update_project_uids** — Resave all resources to update UID references

## Requirements

- **Node.js** >= 18.0.0
- **Godot 4.x** (Mono build recommended for C# support)

## Installation

```bash
npm install -g /path/to/godot-ai-mcp
```

Or use directly via npx:

```bash
npx /path/to/godot-ai-mcp
```

## Configuration

### MCP Config (opencode.json, claude desktop, etc.)

```json
{
  "mcp": {
    "godot-ai": {
      "type": "local",
      "command": [
        "env",
        "GODOT_PATH=/path/to/your/godot/executable",
        "DEBUG=true",
        "npx",
        "-y",
        "godot-ai-mcp"
      ]
    }
  }
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `GODOT_PATH` | Path to the Godot executable (auto-detected if not set) |
| `DEBUG` | Set to `true` for verbose debug output on stderr |

## Usage Examples

### Create a scene with a Player node and attach a script

```
1. create_scene(projectPath="/path/to/project", scenePath="scenes/player.tscn", rootNodeType="CharacterBody2D")
2. add_node(projectPath="/path/to/project", scenePath="scenes/player.tscn", parentNodePath="root", nodeType="Sprite2D", nodeName="Sprite")
3. set_script(projectPath="/path/to/project", scenePath="scenes/player.tscn", nodePath="root", scriptPath="scripts/player.gd")
4. load_sprite(projectPath="/path/to/project", scenePath="scenes/player.tscn", nodePath="root/Sprite", texturePath="assets/player.png")
```

### Inspect and modify a scene

```
1. get_scene_tree(projectPath="/path/to/project", scenePath="scenes/level.tscn")
2. set_node_property(projectPath="/path/to/project", scenePath="scenes/level.tscn", nodePath="root/Enemy", propertyName="position", propertyValue=[100, 200])
3. remove_node(projectPath="/path/to/project", scenePath="scenes/level.tscn", nodePath="root/DebugNode")
```

### Script workflow

```
1. list_scripts(projectPath="/path/to/project")
2. read_script(projectPath="/path/to/project", scriptPath="scripts/enemy.gd")
3. write_script(projectPath="/path/to/project", scriptPath="scripts/enemy.gd", content="extends CharacterBody2D\n...")
```

## Building from Source

```bash
npm install
npm run build
```

The compiled output goes to `build/`. The GDScript file is copied to `build/scripts/`.

## License

MIT — see [LICENSE](LICENSE) for details.

This project is derived from [`@coding-solo/godot-mcp`](https://github.com/Coding-Solo/godot-mcp) (MIT, © Solomon Elias). The original core server architecture, GDScript headless operations pattern, and scene manipulation tools are based on that project.