# 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](https://github.com/rezaahmadn/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)

```bash
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:

```bash
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:

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

### 3. Install the addon (once per Godot project)

```bash
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`](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

```bash
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.