English Français العربية

io.github.Aureliolo/gdharness

Official registry AI and agents

A harness for driving a Godot 4 project from an agent: addons, runtime bridge, MCP server, CLI.

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package gdharness
Claude Code 
claude mcp add gdharness -e 'GODOT_PATH=<GODOT_PATH>' -- npx -y gdharness@1.3.57
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "gdharness": {
            "command": "npx",
            "args": [
                "-y",
                "gdharness@1.3.57"
            ],
            "env": {
                "GODOT_PATH": "<GODOT_PATH>"
            }
        }
    }
}

Environment variables

  • GODOT_PATH Absolute path to the Godot 4.7 or newer executable. Without it, the usual install locations are searched.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. gdharness
  2. Install
  3. The loop it exists for
  4. At a glance
  5. Documentation
  6. Project

gdharness

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
NeedsGodot 4.7 or newer, Node 22 or newer. Runs under Bun 1.4 too.
Surface30 tools named domain_verb, 4 godot:// resources and 3 prompts
ReachesThe editor that is open, a game it is playing, and the project on disk
Harnesses35, written inside the project wherever the harness has a project config
SkillWritten to .agents/skills, which every major harness reads
Installnpm, or a Sigstore-signed archive with an SBOM, SLSA Build Level 3
ProvenEvery tool driven against Godot 4.7.2 in CI, on Windows, Linux and macOS
Status1.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.

Frequently asked questions

What is io.github.Aureliolo/gdharness?

A harness for driving a Godot 4 project from an agent: addons, runtime bridge, MCP server, CLI.

How do I install io.github.Aureliolo/gdharness?

It runs on your machine. In Claude Code: claude mcp add gdharness -e 'GODOT_PATH=<GODOT_PATH>' -- npx -y gdharness@1.3.57. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.Aureliolo/gdharness need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is io.github.Aureliolo/gdharness open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.Aureliolo/gdharness?

It is published by Aureliolo. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.