# Godot Agent Loop [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/beremaran/godot-agent-loop  
**GitHub Stars:** 10  
**npm Downloads (last month):** 849  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/godot-agent-loop

## Description
Evidence-first MCP automation loop with 167 tested tools for Godot 4

## Tools
Capabilities this server exposes over MCP:

- **godot_catalog** — Search or inspect the complete Godot…
- **godot_call** — Execute one named hidden Godot tool…
- **editor_session** — Discover, attach, inspect, or discon…
- **editor_transaction** — Apply one validated compound scene e…
- **run_project** — Run the Godot project and capture ou…
- **verify_project** — Run bounded assertions and capture e…
- **run_project_tests** — Discover or run native, GUT, and GdU…
- **stop_project** — Stop the currently running Godot pro…
- **game_screenshot** — Capture a PNG preview with dimension…
- **game_get_ui** — Get a bounded list of visible UI ele…
- **game_get_scene_tree** — Get scene tree structure of the runn…
- **game_get_node_info** — Get compact or full node info includ…
- **game_wait_until** — Property waits need reflection;
- **game_scenario** — Property waits need reflection;
- **game_get_errors** — Get new push_error/push_warning mess…
- **game_get_logs** — Get new print output from the runnin…

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "godot-agent-loop": {
    "command": "npx",
    "args": ["-y","@beremaran/godot-agent-loop"]
  }
}
```

## Documentation

## What the Godot Agent Loop MCP server does

Godot Agent Loop MCP server gives an MCP client a bounded workflow for working with Godot 4 projects: author, validate, run, observe, playtest, verify, and refine. It is intended for projects using Godot 4.7 or later, with Godot 4.7 as the current compatibility floor and primary target.

The default core surface contains 16 tools. These cover project lifecycle control, editor sessions, compound scene transactions, runtime observation, structured interaction, waiting, project tests, and verification. Coding agents are expected to use their own file tools for direct edits to GDScript, scenes, resources, and project settings, then use this server to run and assess the result.

## How it works

An MCP client launches the server through Node.js and points it at a Godot project directory, including an empty directory for a new project. The server can launch and stop the game, collect logs and errors, inspect the scene tree and UI, retrieve node details, and capture screenshots. It can also compose mouse, keyboard, drag, scroll, touch, and gamepad actions into deterministic scenarios.

Godot Agent Loop MCP server keeps the default tool surface deliberately small. Additional capabilities are found with the read-only `godot_catalog` tool and invoked with `godot_call`. These include extra input methods, performance and visual observations, camera and audio checks, editor controls, import and export checks, add-on tooling, and optional runtime reflection.

With an editor attached, `editor_session` can find the matching project and `editor_transaction` can apply compound, undoable scene changes through Godot's editor undo system. Privileged reflection and code execution are disabled unless explicitly enabled, and the editor includes a human pause control.

## Setup and configuration

Install Node.js 22 or newer and Godot 4.7 or newer. Start the server with an MCP client using:

```bash
claude mcp add godot-agent-loop -- npx -y @beremaran/godot-agent-loop
```

The README specifically documents use with Claude Code, Cline, and Cursor, while other MCP clients may provide their own configuration format. A .NET SDK 8.0 or newer and the Godot .NET build are needed only for .NET project verification with `verify_dotnet_project`.

Rendering and screenshot workflows require a headed rendering context. On Linux, this can be a desktop display or Xvfb; display-less sessions fail with remediation guidance. Privileged runtime operations are intended for trusted localhost development.

## Tools and capabilities

- Start and stop Godot projects.
- Inspect screenshots, scene trees, UI state, node information, logs, and errors.
- Playtest with structured keyboard, mouse, touch, scroll, drag, and gamepad input.
- Wait for conditions and run native, GUT, or GdUnit4 project tests.
- Verify runtime behavior, project integrity, and export readiness.
- Inspect, build, restore, and run Godot .NET projects when the required SDK is installed.
- Use visual-regression comparisons with baselines, masks, and retained differences.

## Limitations and notes

The project does not claim full debugger automation, native extension builds, or unrestricted engine control. Windows support covers portable process, input, window-query, and teardown workflows, but not editor UI, rendering, or exports. Linux editor attachment is verified in CI, and a headed macOS 4.7.1 editor workflow is documented. Export verification claims cover Linux release and debug templates rather than every target platform.

Godot Agent Loop MCP server uses response size caps and deterministic pagination for large results. Runtime injection is transient; projects that need a persistent editor connection can use the optional persistent editor add-on. The documented evidence and integration coverage should be reviewed before relying on a workflow outside the verified support boundary.

_Full upstream README: https://allmcps.com/mcp/godot-agent-loop/readme_