# gregario/godot-forge [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/gregario/godot-forge  
**GitHub Stars:** 8  
**npm Downloads (last month):** 353  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/gregario-godot-forge

## Description
Godot 4 development companion with test running (GUT/GdUnit4), API docs with 3→4 migration mapping, script analysis, scene parsing, screenshots, and LSP diagnostics.

## Tools
Capabilities this server exposes over MCP:

- **godot_run_tests** — Run GUT or GdUnit4 tests headlessly and return structured pass/fail results. Auto-detects the test framework. Returns total/passed/failed counts with failure details including file paths and line numbers.
- **godot_search_docs** — Search Godot 4.x API documentation. Returns class overviews, method details, or fuzzy search results. Automatically detects Godot 3 API queries and suggests Godot 4 equivalents — the #1 source of AI-generated GDScript bugs.
- **godot_get_diagnostics** — Get LSP diagnostics (errors, warnings) from Godot's built-in language server. Requires Godot editor to be running with the project open.
- **godot_analyze_scene** — Parse .tscn scene files or .tres resource files and return structured analysis. Detects antipatterns (deep nesting, oversized scenes, missing scripts) and format errors (preload in .tres, custom class names in type field, integer resource IDs).
- **godot_analyze_script** — Analyse GDScript files for all 10 battle-tested pitfalls: Godot 3→4 API misuse, giant scripts, := on Variant, tight coupling, signal re-entrancy, autoload misuse, missing signal disconnect, _init() timing, Python-isms, and static func on autoloads.
- **godot_run_project** — Launch, stop, or get debug output from a running Godot project. Captures stdout/stderr with timestamps.
- **godot_screenshot** — Capture a viewport screenshot from the running Godot project. Returns base64-encoded PNG image. Requires a display server (not headless mode).
- **godot_get_project_info** — Return project structure overview: project name, Godot version, scenes, scripts, autoloads, addons, and directory tree. Uses progressive disclosure — summary by default, full details on request.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "godot-forge": {
    "command": "npx",
    "args": ["-y","godot-forge"]
  }
}
```

## Documentation

## What gregario/godot-forge MCP server does

gregario/godot-forge MCP server connects an MCP-compatible coding assistant to common Godot 4 development tasks. It exposes eight focused tools rather than a general-purpose wrapper around every Godot operation.

The tools cover automated testing, API documentation lookup, static analysis, scene and resource inspection, project inventory, language-server diagnostics, project execution, and screenshot capture. Results are returned in structured form where applicable, including test counts, failure locations, diagnostic messages, project metadata, and base64-encoded PNG screenshots.

## How it works

The server communicates with the assistant through MCP and locates a Godot project by searching upward from the current directory for `project.godot`. It also searches for the Godot executable automatically. The lookup order starts with `GODOT_PATH`, then checks `godot` or `godot4` on `PATH`, followed by common Steam and platform-specific installation locations.

Godot is not needed for documentation search, script analysis, scene analysis, or project information. Running tests, starting or stopping a project, and taking screenshots use the Godot binary. Language-server diagnostics have a different requirement: the Godot editor must be open with the project loaded.

Test execution detects either GUT or GdUnit4 and can return pass/fail totals plus failure file paths and line numbers. Documentation search handles Godot 4.x queries and can identify older Godot 3 terms, returning suggested Godot 4 equivalents. Project information uses progressive disclosure, providing a summary first and more detail when requested.

## Setup and configuration

Install the gregario/godot-forge MCP server with Node.js 18 or newer:

```bash
npx -y godot-forge
```

Add that command to the MCP configuration for a supported client such as Claude Desktop, Cursor, Windsurf, or Cline. The repository also documents setup for other IDEs.

The project directory is detected automatically. To select a project explicitly, pass its directory with the server's `--project` option. Set `GODOT_PATH` when the automatic executable search does not find the intended Godot binary. Godot 4.x is optional for the tools that only inspect files or documentation, but is needed for execution-related operations.

## Tools and capabilities

- `godot_run_tests` runs GUT or GdUnit4 headlessly, with optional filtering by script, method, or inner class.
- `godot_search_docs` searches Godot 4 API references and supplies migration mappings for deprecated Godot 3 APIs.
- `godot_analyze_script` checks ten documented GDScript pitfalls, including outdated APIs, oversized scripts, unsafe type inference, coupling, signal issues, autoload problems, and Python-style syntax.
- `godot_analyze_scene` parses `.tscn` and `.tres` files, checking nesting, node count, missing scripts, and resource-format problems.
- `godot_get_project_info` reports the project name, Godot version, scenes, scripts, autoloads, addons, and directory tree.
- `godot_get_diagnostics` reads errors and warnings from Godot's built-in language server when the editor is running.
- `godot_run_project` launches or stops a project and captures timestamped standard output and error output.
- `godot_screenshot` captures the running viewport as a base64 PNG and requires a display server rather than headless mode.

## Limitations and notes

gregario/godot-forge MCP server is aimed at Godot 4 workflows. Its migration lookup can suggest replacements for Godot 3 APIs, but that does not make it a Godot 3 tool. Screenshot capture requires a graphical display, and language-server results are unavailable unless the editor has the project open.

The repository describes the package as cross-platform for macOS, Windows, and Linux, including both Steam and non-Steam Godot installations. The source is licensed under MIT. Planned roadmap items such as input simulation, runtime scene-tree inspection, profiling, shader validation, and export or CI support are not listed as current tools.

_Full upstream README: https://allmcps.com/mcp/gregario-godot-forge/readme_