Godot Agent Tools

Let coding agents (Claude Code, Cursor, Cline, Windsurf, Claude Desktop, etc.) work inside your Godot project safely — editing scenes, wiring signals, creating resources, validating references, and running headless smoke tests through the editor's real APIs instead of hand-editing .tscn / .tres / project.godot as text.

48 tools across 13 namespaces. Works with any MCP-capable agent. Godot 4.3+.

The 2-minute install

1. Install the addon in your Godot project.
   • Project → AssetLib tab → search Agent Tools → Download → Install
   • Project → Project Settings → Plugins → tick Agent Tools
2. Point your agent at it. Pick your agent below and paste the snippet into the right config file.
3. Restart your agent and call scene_current to sanity-check. Done.

No Node.js install required — npx downloads the MCP shim on first use.

Why this exists

.tscn, .tres, and project.godot are Godot-specific text formats with fragile invariants: UIDs, sub-resource IDs, inherited-scene overrides, signal [connection] blocks, autoload metadata. An agent editing these as plain text will silently corrupt them. This plugin routes every write through Godot's own PackedScene / ResourceSaver / ClassDB / ResourceUID APIs, so UIDs stay stable, IDs stay unique, and scenes survive round-tripping.

Requirements

• Godot 4.3+ (developed and tested on 4.6)
• Node.js 18+ — only needed the first time npx runs the MCP shim; no manual install
• Any MCP-capable agent

Install

Addon (per Godot project)

Asset Library (recommended):

1. Open your project in Godot
2. Click the AssetLib tab at the top of the editor
3. Search for Agent Tools, hit Download → Install
4. Project Settings → Plugins → enable Agent Tools

Manual (if the Asset Library entry is unavailable):

# From this repo:
cp -r addons/agent_tools /path/to/your/godot/project/addons/

Then enable in Project Settings → Plugins.

MCP shim

No install. The shim is published to npm as godot-agent-tools-mcp. The config snippets below use npx -y godot-agent-tools-mcp, which fetches and caches on first run.

Configure your agent

Pick your agent below. Every snippet is the same two lines ("command": "npx" + "args": ["-y", "godot-agent-tools-mcp"]) — only the file path differs.

Two scopes to choose from:

• Project-scoped: config lives in your Godot project; only that project sees the tools.
• User-scoped: config lives in your home directory; every project on the machine sees the tools.

{
  "mcpServers": {
    "godot-agent-tools": {
      "command": "npx",
      "args": ["-y", "godot-agent-tools-mcp"]
    }
  }
}

{
  "mcpServers": {
    "godot-agent-tools": {
      "command": "npx",
      "args": ["-y", "godot-agent-tools-mcp"]
    }
  }
}

{
  "mcpServers": {
    "godot-agent-tools": {
      "command": "npx",
      "args": ["-y", "godot-agent-tools-mcp"]
    }
  }
}

{
  "mcpServers": {
    "godot-agent-tools": {
      "command": "npx",
      "args": ["-y", "godot-agent-tools-mcp"]
    }
  }
}

{
  "mcpServers": {
    "godot-agent-tools": {
      "command": "npx",
      "args": ["-y", "godot-agent-tools-mcp"]
    }
  }
}

{
  "servers": {
    "godot-agent-tools": {
      "command": "npx",
      "args": ["-y", "godot-agent-tools-mcp"]
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "godot-agent-tools-mcp"]
        }
      }
    ]
  }
}

{
  "context_servers": {
    "godot-agent-tools": {
      "command": {
        "path": "npx",
        "args": ["-y", "godot-agent-tools-mcp"]
      }
    }
  }
}

Environment variables (shim side, optional)

Verify

1. Open your Godot project in the editor; confirm the Output panel shows:

   [agent_tools] listening on 127.0.0.1:9920
   

2. In your agent, run scene_current — should return {"open": true, ...} if a scene is open, or {"open": false} otherwise.
3. Run refs_validate_project — should return {"checked": N, "issues": []} (give or take — issues are real findings).

If either of those returns an error, see Troubleshooting.

Usage

A typical agent-driven flow ("create a main scene with a player"):

scene_new           path=res://Main.tscn root_type=Node2D
scene_add_node      type=CharacterBody2D name=Player
script_create       path=res://scripts/player.gd extends=CharacterBody2D attach_to_node=Player
signal_connect      from=Player signal=body_entered to=. method=_on_player_body_entered
scene_save
refs_validate_project
run_scene_headless  path=res://Main.tscn quit_after_seconds=1

Tool catalog

48 tools across 13 namespaces:

Full JSON schemas live in mcp/server.mjs.

Highlights

• refs.find_usages searches for both the path form and the uid:// form of a target, catching UID-indirected references a plain grep would miss.
• refs.rename moves a file + its .uid and .import sidecars, and rewrites every path-form reference (including project.godot autoload entries). Supports dry_run.
• signal.connect validates that the signal exists on the source, the method exists on the target, and arity matches — before persisting the connection.
• docs.class_ref returns a class's methods / properties / signals / constants straight from ClassDB so agents plan against real API, not hallucinated API.
• run.scene_headless spawns a child godot --headless process and returns exit code + combined stdout/stderr — the only way to catch runtime errors the static validator can't see.
• scene.capture_screenshot saves a PNG of the editor viewport (clean — no grid/gizmos) so agents can verify visual layout. Empty scenes render as the viewport background color.
• refs.rename_class rewrites class_name X and every word-boundary reference across .gd/.tscn/.tres. Complements refs.rename (which is file-based).
• animation.* manipulates AnimationPlayer resources — animations in .tscn text form are one of the least agent-friendly surfaces in Godot.
• scene.build_tree collapses "build a 30-node UI" from dozens of add_node + set_property round trips into a single recursive spec. Atomic: full rollback on any failure.
• scene.call_method / resource.call_method invoke any method with argument coercion — so helpers like StyleBoxFlat.set_border_width_all(4) don't force agents to write a .gd script just to call them.

Skipping MCP — raw TCP protocol

The addon's TCP server speaks line-delimited JSON-RPC. Useful for scripting or non-MCP clients.

Request:

{"id": 1, "method": "scene.current", "params": {}}

Response:

{"id": 1, "result": {"open": false}}

Error:

{"id": 1, "error": {"code": -32001, "message": "no scene open"}}

Quick probe from PowerShell (no deps):

$c=[Net.Sockets.TcpClient]::new('127.0.0.1',9920); $s=$c.GetStream(); $w=[IO.StreamWriter]::new($s); $r=[IO.StreamReader]::new($s); $w.WriteLine('{"id":1,"method":"scene.current","params":{}}'); $w.Flush(); $r.ReadLine(); $c.Close()

Development

If you're hacking on the plugin itself, see CONTRIBUTING.md for conventions. Short version:

1. Adding a tool = three edits (tool file, registry.gd, mcp/server.mjs).
2. After editing GDScript, toggle the plugin off/on in Project Settings → Plugins — hot-reload doesn't always refresh preloaded modules.
3. After editing server.mjs, reload the MCP connection in your agent — the tool list is cached at startup.

To run the shim from source (instead of npm) for dev:

git clone https://github.com/BlakeBukowsky/GodotTools.git
cd GodotTools/mcp
npm install
# Then point your agent's MCP config at:
# "command": "node", "args": ["/abs/path/to/GodotTools/mcp/server.mjs"]

To smoke-test the plugin end-to-end (needs the editor running with plugin enabled):

node tests/smoke.mjs

Exercises ~25 tool calls covering create/read/update/delete flows, cleans up res://__smoketest/ after itself, exits non-zero on the first failure.

Troubleshooting

License

MIT — see LICENSE.

Links

• Godot Asset Library entry (search "Agent Tools")
• npm: godot-agent-tools-mcp
• Issues
• Model Context Protocol