Godot Forge

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:

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.