godot-mcp-gateway

Guides MCP-connected agents through Godot 4.x scene building, scripting, and playtesting workflows.

Updated Aug 20, 2026
One-click install
npx skills add https://github.com/di404/godot-mcp-gateway --skill godot-mcp-gateway-di404
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: godot-mcp-gateway
Source: https://github.com/di404/godot-mcp-gateway/tree/main/addons/godot_mcp_gateway/CompanionSkills/godot-mcp-gateway
Command: npx skills add https://github.com/di404/godot-mcp-gateway --skill godot-mcp-gateway-di404

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Working on a Godot project through MCP tools involves dozens of tool calls, and naive usage wastes tokens, triggers avoidable errors, and corrupts scenes through direct file edits. This Skill encodes the correct tool selection, workflow order, and error recovery patterns so agents build and test Godot 4.x games efficiently through the Godot MCP Gateway. ## Core Features & Use Cases - Tool selection and discovery: Task-to-tool mapping tables, on-demand tool group activation via discover_tools, and decision rules for choosing the cheapest read or mutation tool. - Workflow patterns: Scene creation to playtest verification sequences, batched property mutation, autoload registration, signal wiring, and fast-forward runtime testing with runtime_set_property. - Error recovery and constraints: A debug-first diagnosis loop, a table of common error codes with recovery steps, and hard constraints such as never editing .tscn files directly. - Use Case: An agent asked to build a platformer level follows the dependency-aware build order, batches node creation and property calls, starts the game, simulates input, and verifies state with debugger_get_log instead of expensive screenshots. ## Quick Start Ask the agent to create a new Godot scene with a player node, attach a movement script, and playtest it using the godot-mcp-gateway tools.

Frequently Asked Questions about godot-mcp-gateway

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create and test a Godot scene with MCP tools?

Call scene_create to save a new .tscn, then scene_open to make it active, then scene_create_node for children and node_set_property for values. Save with editor_save_scene, run game_start, activate the runtime group via discover_tools, and verify state with runtime_get_node_state or input_simulate.

How do I reduce token usage with Godot MCP tool calls?

Batch properties in one node_set_property call, activate multiple discover_tools groups in a single call, and prefer node_get_property over scene_get_tree with include_properties. Use debugger_get_log instead of runtime_screenshot for debugging logic, since screenshots cost 5-10x more tokens.

Can multiple AI agents edit the same Godot editor at once?

Yes. A mutation queue and scene lease serialize conflicting work automatically, so under contention responses get slower rather than breaking. Do tab-independent work like scripts, files, and project settings first when another session holds the active scene tab.

Why does my edited GDScript not update on a running node?

On Godot versions before 4.4, editing a script attached to a live node does not reach the running instance, so new methods fail with INVALID_METHOD and changed bodies run old code. Relaunch the editor or write the full script before attaching it; Godot 4.4+ hot-reloads scripts.

Does Godot MCP Gateway work in headless mode?

Headless mode supports building and validation: script_check, lsp_project_diagnostics, editor_get_console, and scene inspection all work. Playtesting is unavailable because there is no display server, so game_start fails with HEADLESS_UNSUPPORTED; verify via state queries and console output instead.

Why should I not edit .tscn files directly in Godot?

Direct .tscn edits bypass the editor's scene tree and cause silent data loss. Always use the MCP scene tools such as scene_create, scene_create_node, and node_set_property so the editor tracks and saves mutations correctly.