Skip to content
AurelioloPublic

About

A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.

Topics

Resources

Contributing

Security policy

Stars

15 stars

Watchers

0 watching

Forks

Repository files navigation

gdharness

CI Scorecard OpenSSF Best Practices OpenSSF Baseline SLSA Build 3 SBOM Signed releases npm Release MCP server MCP 2026-07-28 Made for Godot 4.7+ Node Bun Licence

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 is an MCP server and four Godot addons. Through them the agent asks the open editor and the running game what the screen says and where a control is. It can also ask what a property holds now, what the console printed, and what broke 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/shop" }
runtime_inspect { "op": "find", "says": "Buy" }              // the button, by the word on it
runtime_input   { "op": "click", "nodePath": "/root/Shop/Ledger/BuyButton" }
runtime_inspect { "op": "text", "nodePath": "/root/Shop/Ledger" }   // what the panel says now
editor_output   { "projectPath": "C:/games/shop" }           // errors and warnings, with backtraces

The open editor plays the game, so you can set a breakpoint and read the variables in scope when it stops.

Writes answer with what the engine holds afterwards, never an echo of the request. A tool that cannot answer says which state it is in and what would change it.

At a glance

Needs Godot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.
Surface 32 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, with a copy for Claude Code, Kiro and Cline
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.x: every release is a patch. What a bump means

Godot before 4.7 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 a security fault. CONTRIBUTING.md is what a change has to clear.

Project

Fork of GoPeak v2.3.9, September 2026, MIT. The original MCP server is godot-mcp by Solomon Elias, and GoPeak is by HaD0Yun.

Not affiliated with the Godot Foundation.

About

A harness for driving a Godot 4 project from an agent: editor addons, a runtime bridge into the running game, an MCP server in front of them, and a CLI that installs and diagnoses the Godot side.

Topics

Resources

Contributing

Security policy

Stars

15 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages