gregario/godot-forge

The MCP server for Godot 4. Test runner, API docs, script analysis, and more.
---
AI coding assistants are structurally bad at GDScript. Models trained on data skewed towards Godot 3 hallucinate deprecated APIs (yield instead of await, KinematicBody instead of CharacterBody3D, export var instead of @export var). Godot Forge fixes this.
**8 tools. Zero config. Works with every MCP-compatible IDE.**
Install
That's it. Godot Forge auto-detects your Godot binary (Steam, Homebrew, direct download) and finds your project.godot automatically.
Add to your IDE
Claude Code
Cursor
Add to .cursor/mcp.json:
VS Code (Copilot)
Add to .vscode/mcp.json:
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
Zed
Add to settings.json:
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):
More IDEs (Codex, Gemini CLI, JetBrains, Continue, Cline, Roo Code, Neovim, OpenCode, Kiro)
See IDE Setup Guide for configuration snippets for all supported IDEs.
Tools
| Tool | Description | Needs Godot | Needs Editor |
|------|-------------|:-----------:|:------------:|
| godot_run_tests | Run GUT/GdUnit4 tests, get structured pass/fail results | Yes | No |
| godot_search_docs | Search Godot 4 API docs with 3→4 migration mapping | No | No |
| godot_analyze_script | Detect 10 GDScript pitfalls (deprecated API, coupling, re-entrancy) | No | No |
| godot_analyze_scene | Parse .tscn/.tres, detect antipatterns and format errors | No | No |
| godot_get_project_info | Project structure overview with progressive disclosure | No | No |
| godot_get_diagnostics | LSP diagnostics from Godot's language server | No | Yes |
| godot_run_project | Launch/stop project, capture debug output | Yes | No |
| godot_screenshot | Capture viewport screenshot as base64 PNG | Yes | No |
> [!TIP]
> 6 of 8 tools work without Godot installed. Only test running, project launching, and screenshots need the binary.
Features
Test Runner
Auto-detects GUT and GdUnit4. Returns structured JSON with pass/fail counts, failure details with file paths and line numbers. Supports filtering by script, method, or inner class.
Godot 3→4 Migration Mapping
The #1 reason AI writes broken GDScript. When your AI queries a deprecated API, it gets the correct Godot 4 equivalent instantly (30+ mappings covering classes, methods, syntax, and constants).
Script Analysis: 10 Pitfalls
Every pitfall detected from real game development:
| # | Pitfall | What It Catches |
|---|---------|-----------------|
| 1 | Godot 3→4 API | yield, connect("signal"), export var, instance() |
| 2 | Giant scripts | Over 300 lines. Should be split |
| 3 | := on Variant | Type inference on Dictionary.get() causes parse errors |
| 4 | Tight coupling | Excessive get_node("../../...") references |
| 5 | Signal re-entrancy | Signal emitted between state changes |
| 6 | Autoload misuse | Too many autoloads, static func on autoloads |
| 7 | Missing disconnect | connect() without _exit_tree() cleanup |
| 8 | _init() timing | Node tree access before node is in tree |
| 9 | Python-isms | List comprehensions, len(), Python imports |