内容
# 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).
连接信息
猜你喜欢
暂无推荐服务器