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
• Requirements
• Installation
• Connecting an MCP Client
• Tools
• How It Works / Architecture
• Environment Variables
• Troubleshooting
• Building from Source
• 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

If Godot is not installed, download it from godotengine.org/download.

Installation

1. Clone the repository

git clone <repo-url> 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

Running & Debugging

Discovery & Analysis

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

Visual Verification

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

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

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

Visual tool error table:

Building from Source

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:

npm run watch

To test tools with the MCP Inspector:

npm run inspector

License

This project is licensed under the MIT License.