{ "markdown": "

\n

Godot Forge

\n

The MCP server for Godot 4. Test runner, API docs, script analysis, and more.

\n

\n\n

\n \"npm\n \"npm\n \"MIT\n \"Node.js\n \"MCP\n \"godot-forge\n

\n\n---\n\nAI 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.\n\n**8 tools. Zero config. Works with every MCP-compatible IDE.**\n\n\n \"godot-forge\n\n\n## Install\n\n```bash\nnpx -y godot-forge\n```\n\nThat's it. Godot Forge auto-detects your Godot binary (Steam, Homebrew, direct download) and finds your `project.godot` automatically.\n\n### Add to your IDE\n\n
\nClaude Code\n\n```bash\nclaude mcp add godot-forge -- npx -y godot-forge\n```\n
\n\n
\nCursor\n\nAdd to `.cursor/mcp.json`:\n```json\n{\n \"mcpServers\": {\n \"godot-forge\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"godot-forge\"]\n }\n }\n}\n```\n
\n\n
\nVS Code (Copilot)\n\nAdd to `.vscode/mcp.json`:\n```json\n{\n \"servers\": {\n \"godot-forge\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"godot-forge\"]\n }\n }\n}\n```\n
\n\n
\nWindsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n```json\n{\n \"mcpServers\": {\n \"godot-forge\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"godot-forge\"]\n }\n }\n}\n```\n
\n\n
\nZed\n\nAdd to `settings.json`:\n```json\n{\n \"context_servers\": {\n \"godot-forge\": {\n \"command\": {\n \"path\": \"npx\",\n \"args\": [\"-y\", \"godot-forge\"]\n }\n }\n }\n}\n```\n
\n\n
\nClaude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):\n```json\n{\n \"mcpServers\": {\n \"godot-forge\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"godot-forge\"]\n }\n }\n}\n```\n
\n\n
\nMore IDEs (Codex, Gemini CLI, JetBrains, Continue, Cline, Roo Code, Neovim, OpenCode, Kiro)\n\nSee [IDE Setup Guide](docs/ide-setup.md) for configuration snippets for all supported IDEs.\n
\n\n## Tools\n\n| Tool | Description | Needs Godot | Needs Editor |\n|------|-------------|:-----------:|:------------:|\n| `godot_run_tests` | Run GUT/GdUnit4 tests, get structured pass/fail results | Yes | No |\n| `godot_search_docs` | Search Godot 4 API docs with 3→4 migration mapping | No | No |\n| `godot_analyze_script` | Detect 10 GDScript pitfalls (deprecated API, coupling, re-entrancy) | No | No |\n| `godot_analyze_scene` | Parse .tscn/.tres, detect antipatterns and format errors | No | No |\n| `godot_get_project_info` | Project structure overview with progressive disclosure | No | No |\n| `godot_get_diagnostics` | LSP diagnostics from Godot's language server | No | Yes |\n| `godot_run_project` | Launch/stop project, capture debug output | Yes | No |\n| `godot_screenshot` | Capture viewport screenshot as base64 PNG | Yes | No |\n\n> [!TIP]\n> 6 of 8 tools work without Godot installed. Only test running, project launching, and screenshots need the binary.\n\n## Features\n\n### Test Runner\n\nAuto-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.\n\n```\nAsk your AI: \"Run the water profile tests\"\n→ { total: 5, passed: 5, failed: 0, duration_ms: 462 }\n```\n\n### Godot 3→4 Migration Mapping\n\nThe #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).\n\n```\nQuery: \"KinematicBody\" → \"Renamed to CharacterBody3D in Godot 4\"\nQuery: \"yield\" → \"yield(obj, 'signal') → await obj.signal\"\nQuery: \"instance()\" → \"instance() → instantiate()\"\n```\n\n### Script Analysis: 10 Pitfalls\n\nEvery pitfall detected from real game development:\n\n| # | Pitfall | What It Catches |\n|---|---------|-----------------|\n| 1 | Godot 3→4 API | `yield`, `connect(\"signal\")`, `export var`, `instance()` |\n| 2 | Giant scripts | Over 300 lines. Should be split |\n| 3 | `:=` on Variant | Type inference on `Dictionary.get()` causes parse errors |\n| 4 | Tight coupling | Excessive `get_node(\"../../...\")` references |\n| 5 | Signal re-entrancy | Signal emitted between state changes |\n| 6 | Autoload misuse | Too many autoloads, `static func` on autoloads |\n| 7 | Missing disconnect | `connect()` without `_exit_tree()` cleanup |\n| 8 | `_init()` timing | Node tree access before node is in tree |\n| 9 | Python-isms | List comprehensions, `len()`, Python imports |\n| 10 | .tres type field | Custom class name instead of `type=\"Resource\"` |\n\n### Scene Analysis\n\nParses `.tscn` and `.tres` files. Detects deep nesting (>8 levels), oversized scenes (>100 nodes), missing script references, `preload()` in `.tres`, integer resource IDs, and more.\n\n### LSP Diagnostics\n\nConnects to Godot's built-in language server (runs automatically when the editor is open). Returns real compiler errors and warnings (no guesswork).\n\n> [!NOTE]\n> Requires the Godot editor to be running with your project open. All other tools work without the editor.\n\n### Screenshot Capture\n\nCaptures the game viewport as a PNG image. Loads the project's main scene (or a specified scene), waits for rendering, and returns the screenshot as base64 for the AI to see.\n\n## Configuration\n\n### Godot Binary\n\nAuto-detected in this order:\n\n1. `GODOT_PATH` environment variable\n2. `godot` / `godot4` in PATH\n3. Steam installation (macOS, Windows, Linux)\n4. Platform defaults (`/Applications/Godot.app`, Homebrew, Scoop, Flatpak, Snap, etc.)\n\nOverride manually:\n```bash\nexport GODOT_PATH=\"/path/to/godot\"\n```\n\nSee [Godot Detection](docs/godot-detection.md) for the full list of searched paths.\n\n### Project Directory\n\nAuto-detected by walking up from the current directory to find `project.godot`. Override:\n```bash\nnpx godot-forge --project /path/to/godot/project\n```\n\n## Requirements\n\n- **Node.js 18+**: for `npx` execution\n- **Godot 4.x**: auto-detected (optional for 6 of 8 tools)\n- **Any MCP-compatible IDE**: Claude Code, Cursor, VS Code, Windsurf, Zed, and [more](docs/ide-setup.md)\n\n## Design Principles\n\n- **Outcomes, not operations**: Each tool delivers a complete result, not raw API wrapping\n- **8 curated tools**: No 93-tool context bloat ([why this matters](https://modelcontextprotocol.io/docs/concepts/tools#best-practices))\n- **Progressive disclosure**: Summaries first, details on demand\n- **`spawn()` not `exec()`**: No command injection, no Windows quoting bugs\n- **Actionable errors**: Every error includes a suggestion the AI can act on\n- **Cross-platform**: macOS, Windows, Linux. Steam and non-Steam installs.\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- **Bug reports**: [Open an issue](https://github.com/gregario/godot-forge/issues/new)\n- **Feature requests**: [Start a discussion](https://github.com/gregario/godot-forge/discussions)\n- **Pull requests**: Fork, branch, test, PR\n\n### Development\n\n```bash\ngit clone https://github.com/gregario/godot-forge.git\ncd godot-forge\nnpm install\nnpm run build\nnpm test # 74 tests across 12 test files\n```\n\n### Running locally\n\n```bash\n# Point your IDE at the local build\nclaude mcp add godot-forge-dev -- node /path/to/godot-forge/dist/index.js\n```\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for planned features.\n\n**Phase 2**: Input simulation, runtime scene tree inspection, performance profiling, shader validation, export/CI pipeline.\n\n## Licence\n\n[MIT](LICENSE)", "bytes": 8913, "sha": "2e6117627d9c52b5b034e827a6a87e3d6fde5e4c2fe9b5790c95b1eb8a87a78f", "repo_slug": "gregario/godot-forge", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_gregario_godot_forge_aab693a8/readme" }