# gdharness

gdharness lets an agent inspect and drive a live Godot project, including its UI, node state, input, console output, and debugger.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 25
- Author: Aureliolo
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Aureliolo/gdharness
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/gdharness

## What it does

gdharness connects an agent to a Godot project through project addons, a runtime bridge, an MCP server, and a CLI. The agent can start the editor, locate a control by its visible text, send input, inspect node properties, and collect console output with backtraces. Results come from the engine’s current state rather than from repeating request parameters.

The server exposes 30 tools, 4 `godot://` resources, and 3 prompts. It reaches the open editor, the game it runs, and project files; the editor debugger can pause at a breakpoint and expose variables in scope. Requirements are Godot 4.7 or newer plus Node 22 or newer, with Bun 1.4 supported as well. Godot 4.7 is the compatibility baseline that was tested.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `GODOT_PATH` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env GODOT_PATH=<GODOT_PATH> --transport stdio gdharness -- npx -y gdharness
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add gdharness --env GODOT_PATH=<GODOT_PATH> -- npx -y gdharness
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "gdharness": {
            "command": "npx",
            "args": [
                "-y",
                "gdharness"
            ],
            "env": {
                "GODOT_PATH": "<GODOT_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "gdharness": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "gdharness"
            ],
            "env": {
                "GODOT_PATH": "<GODOT_PATH>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e GODOT_PATH=<GODOT_PATH> gdharness npx -y gdharness
```
Replace <…> with your own values

## When to use it
- start a Godot project from an agent
- locate a UI control by its label
- inspect a node’s text or properties
- send input to a running game
- read editor errors with backtraces

## Example prompts
- Start the project at `C:/games/hall` with `editor_run`, then locate the control labeled “Buy”.
- Use `runtime_input` to click `/root/Hall/Ledger/BuyButton`, then read `/root/Hall/Ledger` with `runtime_inspect`.
- Fetch `editor_output` for `C:/games/hall` and trace the reported error to its source line.

## Similar
- [Pascal 3D Editor](https://affpapa.org/en/nevibecode/mcp/pascal-3d-editor.md) — MCP server · ★ 25085
- [Unity-MCP](https://affpapa.org/en/nevibecode/mcp/unity-mcp.md) — MCP server · ★ 4523
- [mcp](https://affpapa.org/en/nevibecode/mcp/sceneview-mcp.md) — MCP server · ★ 1348
- [Gearboy MCP Server](https://affpapa.org/en/nevibecode/mcp/gearboy-mcp-server.md) — MCP server · ★ 1219
- [ChiR24-unreal_mcp_server](https://affpapa.org/en/nevibecode/mcp/chir24-unreal-mcp-server.md) — MCP server · ★ 975
- [Nova3D](https://affpapa.org/en/nevibecode/mcp/nova3d.md) — MCP server · ★ 733

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md