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.

Related MCP server: Gear

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

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

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.