godot-mcp-bridge

Free, open-source (MIT) MCP server + Godot 4 editor addon that lets AI assistants (Claude Code, etc.) drive the Godot editor and running games: create scenes, edit scripts, simulate input, screenshot gameplay, run test scenarios — 174 tools.

Verified end to end against a real Godot 4.6 editor: a full playable 2D game (scenes, scripts, input map, physics, HUD) was built through these tools alone, then played to completion with simulated input. Sibling project: aseprite-mcp-bridge.

Architecture

Claude / MCP client ── stdio ── godot-mcp-bridge (Node, LISTENS on ws://127.0.0.1:6505-6509)
                                        ▲
                                        │ WebSocket JSON-RPC 2.0 — the addon DIALS OUT
                             Godot editor addon (GDScript)
                                        │ file IPC in the game's user:// dir
                             running game (3 injected autoloads)

The bridge listens; the addon dials in and redials every 3s. Start order never matters, and either side can restart without breaking the other. Ports 6505-6509 mean up to 5 Claude sessions can talk to one editor at once.

Setup

Two one-time steps. After that there is nothing to launch by hand — ever.

1. Build the bridge (once per machine)

git clone https://github.com/rezaahmadn/godot-mcp-bridge.git
cd godot-mcp-bridge
npm install && npm run build

2. Register it with your MCP client (once)

Claude Code, available in every directory:

claude mcp add --scope user godot -- node /absolute/path/to/godot-mcp-bridge/dist/index.js

Or add it to a project's .mcp.json by hand:

{ "mcpServers": { "godot": { "type": "stdio", "command": "node",
  "args": ["/absolute/path/to/godot-mcp-bridge/dist/index.js"] } } }

3. Install the addon (once per Godot project)

mkdir -p /path/to/YourGame/addons
cp -R addons/godot_mcp_bridge /path/to/YourGame/addons/     # or symlink it

Then in Godot: Project → Project Settings → Plugins → enable "Godot MCP Bridge". The bottom panel shows the connection status. The plugin registers three autoloads it needs to inspect a running game; it removes them again when you disable it.

Daily use

Open Godot. Open Claude Code. That's it. No command to type, no server to start.

Claude Code spawns the bridge itself (stdio) when a session starts; the addon in your project dials it as soon as the editor is running. If Godot is not open, the tools simply answer [-32003] Godot editor not connected instead of hanging.

To confirm it is live: claude mcp list should show godot: ✔ Connected (that only means the bridge process is healthy — the editor connection shows in Godot's MCP Bridge bottom panel).

Configuration

Env var	Default	Purpose
GODOT_MCP_PORT	—	pin one exact port instead of scanning
GODOT_MCP_PORT_BASE	6505	first port of the scan range
GODOT_MCP_PORT_COUNT	5	how many ports to try
GODOT_MCP_HOST	127.0.0.1	bind address (localhost only by design)
GODOT_MCP_TIMEOUT_MS	30000	default per-request timeout

Tools

174 across 25 categories: project, resource, scene, scene_3d, node, script, shader, editor, input, input_map, test, runtime, animation, animation_tree, tilemap, navigation, theme, audio, physics, particles, batch, analysis, profiling, export, android. Full inventory in SPEC.md §6.

Gotchas worth knowing:

• Project settings use their full key — application/run/main_scene, not run/main_scene. A wrong key silently creates a new custom setting that Godot ignores.
• Compound values travel as strings: "Vector2(64, 32)", "#ff0000".
• execute_editor_script refuses filesystem-writing APIs unless you pass allow_unsafe_editor_io: true.

Troubleshooting

Symptom	Cause
[-32003] Godot editor not connected	Godot isn't running, or the plugin isn't enabled in this project
Tools work but game tools say "Game is not running"	the game crashed on launch — check Godot's Output panel, or run the project directly
Nothing connects	another Godot editor is already holding the ports; close stray editors

Development

npm run typecheck && npm test    # transport + contract tests
npm run dev                      # run the bridge from source

Built spec-first: SPEC.md is the master contract and specs/ holds self-contained work packages, each implemented and reviewed in parallel.

License

MIT — see LICENSE. Clean-room implementation: the tool surface is API-compatible with a commercial product; all code is original.