Open-Godot-MCP

<!-- SEO/AEO/GEO/LLMO Meta Block ============================= @title: Open Godot MCP — AI Driven Godot Game Development, Testing, and Debugging @description: Open-source MCP server that enables AI to autonomously develop, test, and debug Godot games with deterministic playtesting, online game testing, DAP debugging, LSP integration, and token efficiency. 100% MIT licensed. @keywords: godot mcp, model context protocol, ai game development, godot ai, game testing, playtesting, deterministic testing, online game testing, game debugging, dap debugger, lsp integration, gdscript, godot 4, open-source mcp, ai programming assistant, claude mcp, game engine ai, automated game testing, godot plugin, token efficiency @author: MasterYee Labs @language: en-US @og:type: software @og:title: Open Godot MCP @og:description: Open-source MCP server that enables AI to autonomously develop, test, and debug Godot games with deterministic playtesting, online game testing, DAP debugging, LSP integration, and token efficiency. --> <!-- JSON-LD Structured Data (Schema.org SoftwareApplication) ========================================================= <script type="application/ld+json"> { "@context": "https://schema.org", "@type": "SoftwareApplication", "name": "Open Godot MCP", "applicationCategory": "DeveloperApplication", "operatingSystem": "Cross-platform", "softwareVersion": "0.1.0", "license": "https://opensource.org/licenses/MIT", "description": "Open-source Model Context Protocol server that enables AI to autonomously develop, test, and debug Godot games with deterministic playtesting, online game testing, DAP debugging, LSP integration, and token efficiency.", "url": "https://github.com/masteryee-labs/Open-Godot-MCP", "programmingLanguage": ["GDScript", "Python"], "framework": "Godot Engine 4.5+", "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }, "featureList": [ "Deterministic playtesting (freeze/step/step_until)", "Online game testing (multi-instance, peer simulation)", "DAP debugging (breakpoint, stack_trace, variables, evaluate)", "LSP integration (diagnostics, auto-completion, go-to-definition)", "Token efficiency design (JSON digest, diff, screenshot compression)", "30+ MCP tools, 130+ actions", "Stable online connection (heartbeat, smart reconnection, port auto-avoidance)" ], "aggregateRating": { "@type": "AggregateRating", "ratingValue": "5", "reviewCount": "1" } } </script> --> # Open Godot MCP > Open-source, free, and fully-featured Model Context Protocol (MCP) server that enables AI to autonomously develop, test, and debug Godot games with deterministic playtesting, online game testing, DAP debugging, LSP integration, and token efficiency. 100% MIT licensed, no freemium, no paywall. [](LICENSE) [](https://godotengine.org) [](https://python.org) [](https://modelcontextprotocol.io) **Languages:** [English](README_EN.md) | [繁體中文](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Español](README.es.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Русский](README.ru.md) | [Português-BR](README.pt-BR.md) | [Polski](README.pl.md) | [Italiano](README.it.md) | [Türkçe](README.tr.md) | [ภาษาไทย](README.th.md) | [Tiếng Việt](README.vi.md) | [Bahasa Indonesia](README.id.md) | [Українська](README.uk.md) | [Nederlands](README.nl.md) | [العربية](README.ar.md) | [हिन्दी](README.hi.md) --- ## What is Open Godot MCP? **Open Godot MCP** is an open-source [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI programming assistants (such as Claude, GPT, Cursor, and Windsurf) to the [Godot Engine](https://godotengine.org) editor. It enables AI to **write code, run games, test gameplay, debug at breakpoints, inspect variables, and verify fixes**—all autonomously, without human intervention. Unlike existing Godot MCPs that only allow AI to edit scenes, Open Godot MCP lets AI **actually play games**—through deterministic playtesting (freeze clock → step precise time → observe state → verify results). It is the **only** Godot MCP that supports **online game testing**, **DAP debugger integration**, and **LSP code intelligence**. | Attribute | Value | | --- | --- | | **Project Type** | MCP server (Model Context Protocol) for Godot Engine | | **Target Engine** | Godot 4.5+ (GDScript + C# support) | | **Runtime Environment** | Python 3.11+ (server) + GDScript (addon) | | **License** | MIT (100% open-source, no freemium) | | **Number of Tools** | ~30 MCP tools, ~130 actions | | **Core Features** | Deterministic playtesting, online testing, DAP debugging, LSP integration, token efficiency | | **AI Clients** | Claude Desktop, Cursor, Windsurf, VS Code (MCP), Continue, Zed, any MCP-compatible client | | **Platforms** | Windows, macOS, Linux | | **Unique Capabilities** | Online game testing (not available in other Godot MCPs), DAP + LSP integration | --- ## Why was Open Godot MCP created? Existing Godot MCPs have limitations: | Problem | Existing MCPs | Open Godot MCP | | --- | --- | --- | | AI can't see actual gameplay | Can only edit, not play games or debug | **Deterministic playtesting**—freeze clock, step precise time, step_until condition | | Unstable connections | Hardcoded port, no heartbeat, WSL2 conflicts | Configurable port + heartbeat + smart reconnection + port auto-avoidance | | No online game testing | All MCPs lack multiplayer testing | **Unique**—multi-instance, peer simulation, synchronization verification, network condition injection | | Token inefficiency | Full returns, no PNG compression, no diff | Cheap observation, screenshot compression, diff, digest, incremental queries | | Freemium limitations | Freemium, paid features | **100% MIT open-source**, all features free | --- ## Who is Open Godot MCP for? - **Godot 4 game developers**—want to leverage AI for coding, testing, and debugging - **AI-assisted programmers** (Claude, Cursor, Windsurf, VS Code MCP users)—working on Godot projects - **Independent game studios**—need automated playtesting, don't want to write test frameworks - **Online game developers**—need to test network synchronization, latency, and peer behavior - **Open-source advocates**—want a fully free, no-paywall MCP server --- ## Use Cases | Scenario | How Open Godot MCP helps | | --- | --- | | **AI fixes movement bugs** | AI sets breakpoints → runs game → inspects variables → finds root cause → fixes code → retests | | **Automated boss fight testing** | Freeze clock → spawns boss → steps time → simulates input → verifies player survival | | **Online synchronization verification** | Launches host + client instances → injects latency → compares synchronized state → detects desync bugs | | **Performance analysis** | Takes profiler snapshots → finds spikes → optimizes → remeasures | | **Regression testing** | Runs test suites after code changes → asserts game state matches expectations | | **Level design iteration** | AI creates nodes → arranges scenes → runs game → takes screenshots → adjusts | --- ## Core Capabilities ### 1. Deterministic Playtesting (solves "AI can't see actual gameplay") AI not only writes code but also **plays games to verify and fix**: ``` godot_game play frozen=true # Launches game (frozen clock) godot_exec eval code="GameState.wave = 3" # Sets test scene godot_game_time step_until "boss.size() >= 1" # Waits for boss to appear godot_runtime_state digest # Observes state (JSON, no vision token burn) godot_game_time step ms=500 + dodge input # Plays key moments godot_screenshot game # Takes screenshots only when necessary ``` ### 2. Online Game Testing (unique feature—not available in other Godot MCPs) Capabilities not available in existing Godot MCPs: ``` godot_network launch_instance role="host" # Launches server godot_network launch_instance role="client" # Launches client godot_network network_condition latency=200 # Injects 200ms latency godot_network sync_state # Verifies multi-instance synchronization godot_network simulate_peer count=50 # Stress tests 50 peers ``` ### 3. Token Efficiency Each tool has token-saving design: - **Cheap observation**: JSON state digest instead of screenshots (saves 90% token) - **Diff returns**: Returns only changed parts - **Screenshot compression**: JPEG/WebP + disk storage (not in context) - **Read/write separation**: Read auto-allow, write gate - **Batch operations**: Completes multiple operations in one round-trip ### 4. Stable Connections Solves existing MCP "often can't connect" issues: - Configurable port (env > EditorSettings > auto-avoidance) - Windows Port Reservation detection (avoids Hyper-V/WSL2/Docker reserved ports) - Heartbeat mechanism (actively detects dead connections) - Smart reconnection (exponential backoff + maximum attempts + UI notification) ### 5. Complete Debugging - **DAP (Debugger Adapter Protocol)**: Breakpoints, step, variable inspection (stack_trace, variables, evaluate) - **LSP (Language Server Protocol)**: Static diagnostics, auto-completion, go-to-definition - **Profiler**: Performance snapshots, timeline analysis, spike detection --- ## Getting Started ### 1. Install MCP Server ```bash uv tool install open-godot-mcp # or pip install open-godot-mcp ``` ### 2. Configure AI Client ```json { "mcpServers": { "open-godot-mcp": { "command": "open-godot-mcp" } } } ``` ### 3. Open Godot Project Addon will automatically inject. Open AI client to start using. Complete installation guide in [Docs/06-Installation/Guide.md](Docs/06-Installation/Guide.md). --- ## Tool List ~30 tools, ~130 actions. Read/write separation design. | Domain | Tool | Description | | --- | --- | --- | | Editor | `godot_editor_read/edit` | State, scene, selection | | Scene | `godot_scene` | Create, read, save | | Node | `godot_node_read/edit` | CRUD, properties, groups, signals | | Script | `godot_script` | Diff editing, validation | | Project | `godot_project` | Settings, autoload | | Input Map | `godot_input_map` | InputMap management | | Resources | `godot_resource` | Type-aware viewing | | Animation | `godot_animation` | Create, tracks, defaults | | TileMap | `godot_tilemap` | Cell read/write | | **Game Control** | `godot_game` | Play/stop/freeze | | **Clock** | `godot_game_time` | Freeze/step/step_until | | **Input** | `godot_input` | Keyboard/mouse/gamepad/text | | **State** | `godot_runtime_state` | Digest/watch/signals | | **Injection** | `godot_exec` | Eval/call/assert | | Screenshot | `godot_screenshot` | Compression, saving | | Debugging | `godot_debugger` | DAP breakpoints, stack_trace, variables, evaluate | | Code | `godot_lsp` | Diagnostics, completion | | Performance | `godot_profiler` | Snapshots, timeline | | Testing | `godot_test` | Framework, execution | | **Online** | `godot_network` | Multi-instance, synchronization, network conditions | | Instance | `godot_instance` | Multi-Godot management | | File | `godot_filesystem` | Read/write, search | | Documentation | `godot_docs` | Version mapping | | Log | `godot_log` | Incremental queries | | Batch | `godot_batch` | Multiple operations at once | | Asset | `godot_asset` | Generation, management | | Export | `godot_export` | Defaults, export | | Health | `godot_health` | Connection check | Complete API in [Docs/02-Tools/Index.md](Docs/02-Tools/Index.md). --- ## Comparison with Existing Godot MCPs | Feature | godot-ai | godot-mcp | Coding-Solo | satelliteoflove | thediymaker | **Open Godot MCP** | | --- | --- | --- | --- | --- | --- | --- | | Editor Operations | ✅ | ✅ | ✅ | ✅ | ✅ 149 tools | ✅ | | Actual Gameplay | ⚠️ | ⚠️ | ❌ | ✅ Deterministic | ⚠️ | ✅ **Deterministic + Real-time** | | Online Game Testing | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ **Unique** | | DAP Debugging | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | LSP Integration | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | | Token Efficiency | ⚠️ | ⚠️ | ❌ | ✅ | ❌ | ✅ **Comprehensive** | | Stable Connections | ⚠️ | ❌ | — | ✅ | — | ✅ **Most Stable** | | License | Open-source | Open-source | MIT | MIT | MIT | **MIT** | --- ## Frequently Asked Questions ### What is Model Context Protocol (MCP)? [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that allows AI assistants to connect to external tools and data sources. Open Godot MCP is an MCP server that connects AI to the Godot Engine editor. ### Which Godot versions are supported? Godot 4.5 and later. Addon uses Godot 4.x API, including `EditorDebuggerPlugin`, `EditorInspector`, and debugger message channel. ### Which AI clients are compatible? Any MCP compatible client: Claude Desktop, Cursor, Windsurf, VS Code (MCP extension), Continue, Zed, and any client that supports the Model Context Protocol standard. ### Is C# (Godot .NET) supported? Yes. C# syntax checking and compilation verification are supported. See [Docs/08-CSharp-Support/](Docs/08-CSharp-Support/). ### How does it differ from other Godot MCPs? Open Godot MCP is the **only** Godot MCP that supports connected playtesting, DAP debugger integration (breakpoints, stack trace, variable inspection), and LSP code intelligence. It also has the most comprehensive token efficiency design. ### Is it really free? Yes. 100% MIT licensed, no freemium model, no paywall, no feature limitations. All features are free for everyone. ### Can AI really play games? Yes. Through deterministic playtesting, AI can freeze the game clock, step time precisely, inject test scenarios, simulate player input, observe game state in JSON, and take screenshots - all to verify that code changes are correct. ### How does connected playtesting work? Open Godot MCP can launch multiple Godot instances (host + client), simulate peers, inject network conditions (latency, packet loss), and verify that game state is synchronized across instances. ## Documentation Complete documentation index is available at [Docs/README.md](Docs/README.md). Organized by folder for decoupling design. | Folder | Content | |--------|---------| | [Docs/00-Overview/](Docs/00-Overview/) | Feature overview, design philosophy | | [Docs/01-Architecture/](Docs/01-Architecture/) | Architecture, communication protocol, connection stability, multi-instance, runtime | | [Docs/02-Tools/](Docs/02-Tools/) | Complete tool list (domain-specific files) | | [Docs/03-Realtime-Testing/](Docs/03-Realtime-Testing/) | Deterministic playtesting (Guide + Examples) | | [Docs/04-Token-Efficiency/](Docs/04-Token-Efficiency/) | Token efficiency design (Guide + Strategies) | | [Docs/05-Network-Testing/](Docs/05-Network-Testing/) | Connected playtesting (Guide + Examples) | | [Docs/06-Installation/](Docs/06-Installation/) | Installation (Guide + Troubleshooting) | | [Docs/07-Roadmap/](Docs/07-Roadmap/) | Development roadmap | | [Docs/08-CSharp-Support/](Docs/08-CSharp-Support/) | C# Godot compatibility and syntax checking | | [Docs/09-Research/](Docs/09-Research/) | Existing MCP research, C# MCP research | ## Acknowledgements Open Godot MCP stands on the shoulders of giants, taking the best and leaving the rest from the following projects: - [Coding-Solo/godot-mcp](https://github.com/Coding-Solo/godot-mcp) (4.8k stars) - foundational architecture - [satelliteoflove/godot-mcp](https://github.com/satelliteoflove/godot-mcp) - deterministic playtesting, cheap observation, read/write separation - [hi-godot/godot-ai](https://github.com/hi-godot/godot-ai) - debugger channel runtime, Undo/Redo, Windows port reservation, 20+ client configurations, McpTestSuite - [tomyud1/godot-mcp](https://github.com/tomyud1/godot-mcp) - dual-channel architecture, Variant serialization, deletion protection - [rosskarchner/godot-mcp](https://github.com/rosskarchner/godot-mcp) - DAP + LSP integration, multi-instance, port isolation - [Erodenn/godot-mcp-runtime](https://github.com/Erodenn/godot-mcp-runtime) - zero-footprint, Playwright for Godot concept - [thediymaker/godot-mcp](https://github.com/thediymaker/godot-mcp) - 149 tools' functional breadth reference ## License [MIT](LICENSE) - 100% open-source, all features free, no freemium, no paywall.