# Godot MCP Flash

A **Model Context Protocol (MCP) server** for interacting with the Godot game engine. It lets AI agents (Claude, Cursor, Cline, Codex, opencode, etc.) inspect, modify, run, and debug a Godot project directly.

This project is a streamlined and extended fork of the popular [`Coding-Solo/godot-mcp`](https://github.com/Coding-Solo/godot-mcp). It keeps the shared architecture and adds visual verification, project discovery, and scene/script analysis tools on top.Thank you for making this possible with your excellent open-source work!

---

## Table of Contents

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Connecting an MCP Client](#connecting-an-mcp-client)
- [Tools](#tools)
- [How It Works / Architecture](#how-it-works--architecture)
- [Environment Variables](#environment-variables)
- [Troubleshooting](#troubleshooting)
- [Building from Source](#building-from-source)
- [License](#license)

---

## Features

- **Editor Management**: Launch the Godot editor, close it, read its console output.
- **Running Projects**: Run a project or a single scene in debug mode, capture output/errors, and stop it.
- **Scene Management**: Create scenes, add nodes, load sprites/textures, export MeshLibrary resources, and save scenes.
- **Project Discovery**: List browsable Godot projects and find files within a project by category.
- **Scene & Script Analysis**: Read a `.tscn` scene's hierarchy and a `.gd` script's contents as structured JSON.
- **Script Validation**: Check one or many `.gd` scripts for syntax errors without running them.
- **Visual Verification**: Render a scene and return a screenshot (requires a real display).
- **UID Management** (Godot 4.4+): Read file UIDs and update project references.

---

## Requirements

| Component | Requirement |
|---|---|
| Godot Engine | 4.x (4.4+ recommended) |
| Node.js | >= 24.0.0 |
| npm | bundled with Node |

If Godot is not installed, download it from [`godotengine.org/download`](https://godotengine.org/download).

---

## Installation

### 1. Clone the repository

```bash
git clone <repo-url> godot-mcp-flash
cd godot-mcp-flash
```

### 2. Install dependencies and build

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

During `npm install`, the `prepare` script automatically runs the build. After building, two GDScript files are copied into `build/scripts/`:

- `godot_operations.gd` — mutating operations such as creating scenes, adding nodes, and loading sprites.
- `godot_insights.gd` — scene and script analysis (read-only).

The server entry point is `build/index.js`.

---

## Connecting an MCP Client

### Claude Code

```bash
claude mcp add godot -- npx godot-mcp-flash
```

If the Godot path cannot be auto-detected, specify it with an environment variable:

```bash
claude mcp add godot -e GODOT_PATH=/path/to/godot -- npx godot-mcp-flash
```

### Cline

Add to your MCP settings file (`cline_mcp_settings.json`):

```json
{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-flash"],
      "env": {
        "GODOT_PATH": "C:\\Godot\\Godot_v4.7.1\\Godot_v4.7.1-stable_win64.exe"
      },
      "autoApprove": [
        "launch_editor",
        "run_project",
        "run_scene",
        "get_debug_output",
        "stop_project",
        "quit_godot",
        "view_log",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "list_project_files",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids",
        "get_scene_insights",
        "get_node_insights"
      ]
    }
  }
}
```

### Cursor

**Via the Cursor UI:** `Cursor Settings > Features > MCP > + Add New MCP Server` → name `godot`, type `command`, command `npx godot-mcp-flash`.

**Project-level** (`.cursor/mcp.json`):

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

### opencode

Add the server to your `opencode.json` (or `opencode.jsonc`) under the `mcp` key:

```json
{
  "mcp": {
    "godot": {
      "type": "local",
      "command": ["npx", "godot-mcp-flash"],
      "enabled": true,
      "environment": {
        "GODOT_PATH": "C:\\Godot\\Godot_v4.7.1\\Godot_v4.7.1-stable_win64.exe"
      }
    }
  }
}
```

On Linux/macOS, replace `GODOT_PATH` with the path to your Godot binary. On Windows, use a full absolute path with escaped backslashes.

### Generic MCP Client

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

> **Windows note**: Always provide a full absolute path, e.g. `"GODOT_PATH": "C:\\Godot\\Godot_v4.7.1\\Godot_v4.7.1-stable_win64.exe"`. Auto-detection scans common locations if `godot` is not on PATH, but setting the variable yourself is the reliable approach.

---

## Tools

### Editor & Process Management

| Tool | Description | Inputs |
|---|---|---|
| `launch_editor` | Opens the Godot editor for a specific project. | `projectPath` |
| `quit_godot` | Closes the editor that this server launched via `launch_editor`. | — |
| `view_log` | Returns the console output of the last launched editor. | `lineCount` (optional, default 50, max 1000) |
| `get_godot_version` | Returns the installed Godot version. | — |

### Running & Debugging

| Tool | Description | Inputs |
|---|---|---|
| `run_project` | Runs the project in debug mode and captures output. | `projectPath`, `scene` (optional) |
| `run_scene` | Runs a single scene (F6-style) with an auto-stop timeout. | `projectPath`, `scenePath`, `timeoutMs` (optional, default 30000) |
| `get_debug_output` | Returns the active process's output and error lines. | — |
| `stop_project` | Stops the running project. | — |

### Discovery & Analysis

| Tool | Description | Inputs |
|---|---|---|
| `list_projects` | Lists Godot projects in a directory. | `directory`, `recursive` (optional) |
| `get_project_info` | Project name, Godot version, and file statistics. | `projectPath` |
| `list_project_files` | Lists scenes, scripts, and resources by category. | `projectPath`, `pattern` (glob, optional), `type` (`scene`/`script`/`resource`/`all`) |
| `get_scene_insights` | Returns a `.tscn` scene's node hierarchy, attached scripts, and signal connections. | `projectPath`, `scenePath`, `includeProperties`, `includeConnections`, `includeScriptInsights` (optional) |
| `get_node_insights` | Returns a `.gd` script's class structure, signals, exports, methods, and dependencies. | `projectPath`, `scriptPath`, `includeMethods`, `includeVariables`, `includeDependencies` (optional) |
| `validate_script` | Checks one `.gd` script with Godot's headless syntax checker. | `projectPath`, `scriptPath`, `timeoutMs`, `maxOutputBytes` (optional) |
| `validate_scripts` | Checks explicit scripts or all project scripts, with bounded batch processing. | `projectPath`, `scriptPaths`, `scope`, `timeoutMs`, `maxFiles`, `maxOutputBytes` (optional) |

Validation tool inputs use camelCase names as shown. The equivalent snake_case aliases `project_path`, `script_path`, `script_paths`, `timeout_ms`, `max_files`, and `max_output_bytes` are also accepted and normalized automatically. `maxFiles` is capped at 1000, and `maxOutputBytes` is a combined stdout/stderr cap capped at 256 KiB.

### Scene Editing

| Tool | Description | Inputs |
|---|---|---|
| `create_scene` | Creates a new scene with the given root node type. | `projectPath`, `scenePath`, `rootNodeType` (default `Node2D`) |
| `add_node` | Adds a node to an existing scene, optionally setting properties. | `projectPath`, `scenePath`, `nodeType`, `nodeName`, `parentNodePath` (default `root`), `properties` (optional) |
| `load_sprite` | Loads a texture onto a `Sprite2D`/`Sprite3D`/`TextureRect` node. | `projectPath`, `scenePath`, `nodePath`, `texturePath` |
| `export_mesh_library` | Exports a scene as a `MeshLibrary` resource for GridMap. | `projectPath`, `scenePath`, `outputPath`, `meshItemNames` (optional) |
| `save_scene` | Saves a scene, or saves it to a new path (variant). | `projectPath`, `scenePath`, `newPath` (optional) |

### Visual Verification

| Tool | Description | Inputs |
|---|---|---|
| `capture_screenshot` | Runs a scene and returns one rendered frame as an image. | `projectPath`, `scenePath` (optional), `waitFrames` (default 10), `timeoutMs` (default 15000) |
| `capture_scene_screenshot` | Loads a `.tscn` file and captures one frame. | `projectPath`, `scenePath`, `timeoutMs` (optional) |

> **Visual tools require a real display** (they are not `--headless`). On headless Linux, wrap Godot with `xvfb-run` (see below).

### UID Management (Godot 4.4+)

| Tool | Description | Inputs |
|---|---|---|
| `get_uid` | Returns the UID for a specific file. | `projectPath`, `filePath` |
| `update_project_uids` | Updates UID references by resaving resources. | `projectPath` |

---

## How It Works / Architecture

The server uses two primary approaches:

1. **Direct commands** — simple operations such as `launch_editor`, `run_project`, and `get_godot_version` use Godot's built-in CLI arguments directly (`--editor`, `--path`, `--version`).

2. **Bundled GDScript operations** — complex operations such as `create_scene`, `add_node`, `load_sprite`, and `get_scene_insights` are executed by two GDScript files that are copied into `build/scripts/` during build:

   - `godot_operations.gd` — packs/saves scenes, adds nodes, and writes resources.
   - `godot_insights.gd` — parses `.tscn` and `.gd` files **as plain text** (no `ResourceLoader` needed, so it also works in headless environments).

Both scripts receive an operation name and parameters as JSON and print the result to stdout, avoiding temporary files per operation.

The `capture_screenshot` tools run Godot **without** `--headless` to produce real pixels and return the PNG as a base64 `image` block.

### Security Notes

- Path validation blocks `..` traversal and **NUL byte (poison-null-byte)** attacks.
- Class-name validation prevents arbitrary script instantiation (only `[A-Za-z_][A-Za-z0-9_]*` identifiers are accepted).
- Godot execution uses argument arrays (`execFile`/`spawn`) that bypass shell interpretation entirely, so there is no command-injection risk.

---

## Environment Variables

| Variable | Description |
|---|---|
| `GODOT_PATH` | Full path to the Godot executable (overrides auto-detection). |
| `DEBUG` | When set to `"true"`, prints detailed debug logging (to stderr). |

### Example: screenshots on headless Linux

On a machine without a real display, create a virtual-display wrapper script:

```bash
#!/bin/sh
# /usr/local/bin/godot-xvfb
exec xvfb-run -a /usr/bin/godot "$@"
```

```bash
chmod +x /usr/local/bin/godot-xvfb
export GODOT_PATH=/usr/local/bin/godot-xvfb
```

---

## Troubleshooting

| Problem | Fix |
|---|---|
| `Could not find a valid Godot executable path` | Set the `GODOT_PATH` environment variable to a full path. |
| `Not a valid Godot project` | Ensure the path points to a directory containing `project.godot`. |
| Visual tools report `Viewport returned an empty image` | No real display; use `xvfb-run` on headless Linux. |
| `Build Issues` | Re-run `npm install` and `npm run build`. |
| Tools don't show up in Cursor | Confirm the MCP server is enabled under `Settings > MCP` and that you're using the Agent profile (Pro/Business). |

**Visual tool error table:**

| Error | Likely cause | Fix |
|---|---|---|
| `Viewport returned an empty image` | Headless Linux, no virtual display | Use `xvfb-run` |
| `Failed to load scene` | Wrong `scenePath` | Confirm the `res://` prefix and that the file exists |
| `timed out after 15000ms` | Scene loading slowly or crashing | Increase `timeoutMs` or run `run_project` first to see errors |

---

## Building from Source

```bash
git clone <repo-url> godot-mcp-flash
cd godot-mcp-flash
npm install
npm run build
```

Then point your MCP client directly at `build/index.js` instead of `npx godot-mcp-flash`.

To watch files during development:

```bash
npm run watch
```

To test tools with the MCP Inspector:

```bash
npm run inspector
```

---

## License

This project is licensed under the [MIT License](LICENSE).