Godot Mcp Flash

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

---

Installation

1. Clone the repository

git clone  godot-mcp-flash
cd godot-mcp-flash

2. Install dependencies and build

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

claude mcp add godot -- npx godot-mcp-flash

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

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

{
  "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):

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

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

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

1. 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:

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

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

git clone  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:

npm run watch

To test tools with the MCP Inspector:

npm run inspector

---

License

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: gurolayanlar
• Source: gurolayanlar/godot-mcp-flash
• License: MIT

Install and usage instructions live in the source repository linked above.