About gdharness
gdharness is a harness for driving and inspecting Godot 4 projects, for agents and developers who need to observe a running game. It reads results from the engine, including screen content, control positions, live properties, and editor errors.
Key features
- 01Drive a running Godot game
- 02Inspect screen text and controls
- 03Read live properties and console output
- 04Access four Godot resources
- 05Use 30 tools and three prompts
Use cases
- 01Check whether a game button appears
- 02Verify a panel’s updated text
- 03Read runtime errors and backtraces
- 04Inspect variables when the debugger pauses
MCP support
Provides an MCP server with 30 tools, four `godot://` resources, and three prompts for interacting with the open editor, running game, and project files.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y gdharnessGODOT_PATHAbsolute path to the Godot 4.7 or newer executable. Without it, the usual install locations are searched.Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
30Saved tool list · updated today
| Parameter | Type | Required | Description |
|---|---|---|---|
| detail | enum | No | full adds what to do about it to every validation finding. Default summary.summary | full |
| preset | string | No | For validation: the export preset to validate against. |
| include | array | No | Extra sections: registered autoloads, addons and whether each is enabled, export presets, the audio bus layout, a health report, or export validation. |
| projectPath | string | Yes | Absolute path to the project directory, the one holding project.godot. |
Details
From the project READMEgdharness
An agent cannot see a running game. It reads your scripts and guesses at the rest: whether the button is on screen, whether the panel updated, whether that error mattered.
gdharness makes the engine answerable instead. What the screen says, where a control is, what a property reads right now, what the console printed, what broke and on which line.
Install
Hand this to your agent:
Install gdharness here by following https://aureliolo.github.io/gdharness/agent.md,
then tell me what it asked you to recommend back to me.
Or do it yourself, and pick your harness: aureliolo.github.io/gdharness.
The loop it exists for
editor_run { "op": "start", "projectPath": "C:/games/hall" }
runtime_inspect { "op": "find", "says": "Buy" } // the button, by the word on it
runtime_input { "op": "click", "nodePath": "/root/Hall/Ledger/BuyButton" }
runtime_inspect { "op": "text", "nodePath": "/root/Hall/Ledger" } // what the panel says now
editor_output { "projectPath": "C:/games/hall" } // errors and warnings, with backtraces
The open editor plays the game, so its debugger holds it, which is what lets you set a breakpoint and read the variables in scope when it stops.
Every answer is read back out of the engine after the fact, never echoed from the request. A tool that cannot answer says which state it is in and what would change it, rather than answering emptily, so a call that succeeded is a call that was understood.
At a glance
| Needs | Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too. |
| Surface | 30 tools named domain_verb, 4 godot:// resources and 3 prompts |
| Reaches | The editor that is open, a game it is playing, and the project on disk |
| Harnesses | 35, written inside the project wherever the harness has a project config |
| Skill | Written to .agents/skills, which every major harness reads |
| Install | npm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3 |
| Proven | Every tool driven against Godot 4.7.2 in CI, on Windows, Linux and macOS |
| Status | 1.0: every release is a patch. What a bump means |
Older 4.x is likely to work and is not tested.
Documentation
aureliolo.github.io/gdharness: installing it, how the parts connect, and every tool, op and argument.
SECURITY.md is how to report something. CONTRIBUTING.md is what a change has to clear.
Project
Fork of GoPeak v2.3.9, September 2026, MIT: the original MCP server godot-mcp by Solomon Elias, GoPeak by HaD0Yun, and completely reworked since to be hardened, condensed and more streamlined.
Not affiliated with the Godot Foundation.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.