# Golem MCP — AI Bridge for Godot 4.x

**v2.3.1**

Connect your AI coding agent to the Godot editor. Live scene manipulation, real-time screenshots, instant feedback loop — all through MCP over a persistent TCP connection.

Works with **Claude Code**, **Cursor**, **Windsurf**, **Continue.dev**, and **Cline**.

## Features

- **35 MCP Tools** — Scenes, scripts, screenshots, input simulation, project settings, node manipulation, signals, anchors, resources, themes
- **9 Commands** — `/think`, `/fix`, `/build`, `/learn`, `/ship`, `/init`, `/checkpoint`, `/deliverable`, `/references`
- **18 Expert Skills + router** — Internal skills invoked by commands: plan, sequence, simulate, gate, architecture, scene, composition, behavior, juice, vfx, audio, camera, save, debug, test, theme, design-audit, status — plus the `/godot` router and skill index
- **7 Auto-loaded Rules** — GDScript guardrails, shader/VFX safety, recipe gates, MCP pitfall prevention, audio, game feel, multi-agent orchestration
- **5 Hooks** — Connection check, .tscn protection, GDScript lint, context restore, pre-compaction backup
- **20 Recipes & 2 References** — Tested implementation techniques and pitfall checklists injected before you build

## Quick Start

```bash
# Install into your Godot project
uvx golem-mcp install /path/to/your/godot-project

# Enable the plugin in Godot
# Project > Project Settings > Plugins > Golem MCP (checkbox)

# Open your project in Claude Code and type:
/think
```

## Installation

### Option 1 — CLI (recommended)

```bash
uvx golem-mcp install /path/to/your/godot-project
```

This copies the plugin, commands, skills, rules, hooks, recipes, references, and generates configs automatically.

Then enable the plugin in **Godot > Project Settings > Plugins > Golem MCP**.

### CLI Options

```bash
# Choose your AI assistant
uvx golem-mcp install /path/to/project --agent cursor
uvx golem-mcp install /path/to/project --agent windsurf

# Force overwrite existing install
uvx golem-mcp install /path/to/project --force

# Use a local clone (for development)
uvx golem-mcp install /path/to/project --local /path/to/golem-mcp

# Skip skills installation
uvx golem-mcp install /path/to/project --skip-skills

# Uninstall
uvx golem-mcp uninstall /path/to/project
```

### Manual installation

<details>
<summary>If you prefer to install manually</summary>

#### 1. Godot Plugin

Copy `package/godot-plugin/` into your project:

```
your-project/addons/golem-mcp/ <- contents of package/godot-plugin/
```

Enable: **Project > Project Settings > Plugins > Golem MCP**

#### 2. MCP Server

```bash
cd golem-mcp
uv sync
```

#### 3. Claude Code Config

Create `.mcp.json` at your project root:

```json
{
  "mcpServers": {
    "godot": {
      "type": "stdio",
      "command": "uvx",
      "args": ["golem-mcp"]
    }
  }
}
```

#### 4. Skills & Rules

Copy into `.claude/`:

```
.claude/
  commands/    <- package/commands/*.md
  skills/      <- package/skills/*.md
  rules/       <- package/rules/*.md
  hooks/       <- package/hooks/*.py
  tools/       <- package/tools/*.py
```

Copy at project root:

```
recipes/       <- package/recipes/
references/    <- package/references/
```

</details>

### What gets installed

```
your-project/
├── addons/golem-mcp/          # Godot plugin (TCP server + handlers)
├── .claude/
│   ├── commands/              # Slash commands
│   ├── skills/                # Internal skills (invoked by commands)
│   ├── rules/                 # Auto-loaded rules (by glob pattern)
│   ├── hooks/                 # Python hooks
│   ├── tools/                 # Pre-flight and validation scripts
│   └── settings.json          # Hook configuration
├── recipes/                   # Tested implementation techniques
├── references/                # GDScript pitfalls, workflow patterns
├── .mcp.json                  # MCP server config
└── CLAUDE.md                  # Project context for the AI agent
```

## Architecture

```
GolemServer (GDScript @tool, multi-client TCP :3571)
│   └─ _handlers{} ──→ 8 handler nodes (35 tools)
│
←── TCP/JSON lines (:3571, max 5 clients)
    ├─ golem_mcp.py (FastMCP/Python) ←stdio/MCP→ Claude Code
    ├─ golem_mcp.py ←stdio/MCP→ Cursor / Windsurf
    └─ ... (multi-client)
```

## Tools (35)

| Tool | Description |
|------|-------------|
| `godot_get_scene_tree` | Scene tree hierarchy (`detail_level`: full/summary) |
| `godot_inspect_node` | Node properties, signals, groups |
| `godot_get_editor_screenshot` | Editor viewport capture |
| `godot_get_game_screenshot` | Running game capture (via GolemCapture autoload) |
| `godot_play_scene` | Run a scene |
| `godot_stop_scene` | Stop the running scene |
| `godot_get_errors` | Retrieve errors |
| `godot_clear_logs` | Clear logs |
| `godot_execute_script` | Run GDScript in the editor context |
| `godot_view_script` | Read a script file |
| `godot_write_script` | Write a .gd file |
| `godot_attach_script` | Attach a script to a node |
| `godot_add_node` | Create a node (supports `unique_name` for %Name access) |
| `godot_add_nodes` | Batch: create a full node hierarchy (supports `unique_name` per node) |
| `godot_delete_node` | Delete a node |
| `godot_update_property` | Modify a node property |
| `godot_move_node` | Move a node in the tree |
| `godot_duplicate_node` | Duplicate a node |
| `godot_find_nodes` | Search nodes by type, group, name, script |
| `godot_create_scene` | Create a new scene |
| `godot_open_scene` | Open an existing scene |
| `godot_save_scene` | Save the current scene |
| `godot_create_sprite_frames` | Create SpriteFrames with animations and assign to a node |
| `godot_get_input_map` | Read project-defined input actions (filters out built-in) |
| `godot_project_settings` | Read/write project settings |
| `godot_project_context` | Full project dump (settings, autoloads, input map, files) |
| `godot_get_logs` | Game + engine logs (incremental) |
| `godot_simulate_input` | Simulate input sequences in the running game |
| `godot_list_resources` | List project files by type/extension and directory |
| `godot_get_signals` | List signals and connections of a node |
| `godot_connect_signal` | Connect a signal between two nodes |
| `godot_set_anchor` | Set anchor preset on a Control node (fixes offset pitfall) |
| `godot_add_resource` | Create and save a standalone .tres resource file |
| `godot_create_theme` | Create a Godot Theme resource with design tokens |
| `godot_edit_script` | Find-and-replace in a script file (Godot auto-reload) |

## Commands & Skills

### Commands (user-facing)

Slash commands — the entry points for all workflows:

| Command | Role |
|---------|------|
| `/think` | Brainstorm, design, plan — read-only, no code changes |
| `/fix` | Debug, diagnose, repair — sequential investigation |
| `/build` | Implement a deliverable — pre-flight, construct, validate |
| `/learn` | Extract session feedback into reusable knowledge |
| `/ship` | Version sync, clean dist, build for PyPI |
| `/init` | Bootstrap a new Godot project from vision to structure |
| `/checkpoint` | Snapshot current project state |
| `/deliverable` | Focus work on completing a specific deliverable |
| `/references` | Extract reusable patterns from the current project |

### Skills (internal)

Specialist skills invoked by commands via the `/godot` router — not called directly:

| Skill | Domain |
|-------|--------|
| `godot` | Router — dispatches intent to the correct skill |
| `godot-plan` | Interrogation + mini-PRD before building |
| `godot-sequence` | Game flow as structured YAML |
| `godot-simulate` | Paper-prototyping (narrative, balance, exhaustive) |
| `godot-gate` | Pre-construction validation checklist |
| `godot-architecture` | Modular pseudo-ECS design (EventBus, components) |
| `godot-scene` | Scene construction via MCP tools |
| `godot-composition` | UI structure: design tokens, containers, layout |
| `godot-behavior` | UI states, transitions, tweens, feedback loops |
| `godot-juice` | Game feel: screenshake, freeze, squash, trails |
| `godot-vfx` | Particles, shaders, lighting, WorldEnvironment |
| `godot-audio` | Bus layout, music, SFX, spatial audio |
| `godot-camera` | 2D camera: follow, zoom, limits, cinematic |
| `godot-save` | Save/load: settings, game state, slots, migration |
| `godot-debug` | Sequential diagnostic methodology |
| `godot-test` | Automated tests: input simulation + logs + verification |
| `godot-theme` | Design token system via Godot Theme resource |
| `godot-design-audit` | UX audit via screenshots, phased improvement report |
| `godot-status` | Scan project state, generate DEVLOG, track progress |

### Rules (auto-loaded)

Rules loaded automatically when file patterns match:

| Rule | Glob Pattern | Purpose |
|------|-------------|---------|
| `gdscript.md` | `**/*.gd` | Timing, types, architecture patterns |
| `shaders.md` | `**/*.gdshader`, `**/vfx/**` | VFX, lighting, game feel |
| `recipes.md` | `**/*.gd`, `**/*.gdshader` | Gate: consult recipes before implementing |
| `mcp-pitfalls.md` | `**/*.gd`, `godot-plugin/**` | Plugin/TCP, tools MCP, runtime pitfalls |
| `audio.md` | `**/*.gd` | Audio guardrails |
| `game-feel.md` | `**/*.gd` | Game feel guardrails |
| `multi-agent.md` | always | Multi-agent orchestration for game dev |

## Hooks

| Hook | Event | Role |
|------|-------|------|
| `check_connection.py` | PreToolUse (godot_*) | Checks TCP connection before MCP calls (cached, TTL 10s) |
| `block_tscn_edit.py` | PreToolUse (Edit/Write) | Blocks direct .tscn file editing |
| `gdscript_lint.py` | PostToolUse (godot_write_script) | Lints GDScript after writing |
| `pre_compact.py` | PreCompact | Saves project state before context compaction |
| `compact_context.py` | SessionStart (compact) | Restores project context after compaction |

## Workflow

### Planning a new game

```
/think  →  (validate plan)  →  /build  →  /learn
```

1. **`/think`** — Define vision, mechanics, target feeling. Produces `GAME_PLAN.md`
2. Review and validate the plan
3. **`/build`** — Implement phase by phase (pre-flight checks recipes and pitfalls automatically)
4. **`/learn`** — Extract what worked into reusable knowledge

### Fixing a bug

```
/fix
```

Direct route — sequential diagnosis, no prerequisites.

### Building a feature

```
/build "add patrol enemy with waypoints"
```

The `/build` command runs pre-flight (matches recipes, surfaces pitfalls, finds relevant project files), then constructs using the appropriate skills.

### Quick prototyping

```
/build "quick: test particle effect on player hit"
```

For testing an idea fast. No plan or architecture overhead.

## Agent Teams

Run multiple Claude Code agents on the same Godot project simultaneously. A lead agent orchestrates teammates, each with their own TCP connection to the plugin (max 5 clients).

The installer enables the feature flag automatically. See [docs/AGENT_TEAMS.md](docs/AGENT_TEAMS.md) for full documentation.

```
Lead Agent
├── Task → Teammate A (own files, own MCP connection)
├── Task → Teammate B
└── Task → Teammate C
         GolemServer (TCP :3571, max 5 clients)
```

Key rules:
- Each teammate owns specific files (`FILES_OWNED`) — no overlap
- Only the lead calls `godot_save_scene`
- Max 5 simultaneous connections (lead + 4 teammates)

## Troubleshooting

### "Connection refused" / Port unavailable

**Symptom**: The `check_connection.py` hook blocks with "Godot is not connected"

**Possible causes**:
1. Godot is not open
2. The Golem MCP plugin is not enabled
3. Another process is using port 3571

**Solutions**:
```bash
# Check if port is in use
lsof -i :3571        # macOS/Linux
netstat -ano | findstr :3571  # Windows

# Change port (if conflict)
export GOLEM_PORT=3572  # Before launching Claude Code
```

In Godot: **Project > Project Settings > Plugins > Golem MCP** must be enabled.

### "No scene is currently running" (screenshot)

Run the game with `godot_play_scene` before capturing with `godot_get_game_screenshot`.

### Empty screenshot / base64 error

**Possible causes**:
1. `GolemCapture` autoload not active — check Project Settings > Autoload
2. The game crashed before capture — use `godot_get_errors`
3. Race condition — wait before capturing after `play_scene`

### Lint warnings after godot_write_script

This is normal — lint is a safety net. Common warnings:
- `Missing 'extends'` — add `extends Node` (or correct type)
- `':=' with Variant source` — replace `:=` with `: Type =` for Array, Dict, ternary, `.duplicate()`
- `await inside _process` — forbidden in @tool scripts, use deferred pattern

### Ghost connections in Godot logs

Fixed — the server silently ignores probe connections. Update the plugin if you see this.

## TCP Protocol

JSON lines on port 3571 (configurable via `GOLEM_PORT` env var). Multi-client, max 5 simultaneous connections.

**Request:** `{"id": "uuid", "tool": "get_scene_tree", "args": {}}\n`

**Response:** `{"id": "uuid", "ok": true, "result": "...", "type": "text"}\n`

**Image response:** `{"id": "uuid", "ok": true, "result": "base64...", "type": "image", "mime": "image/jpeg"}\n`

## Development

```bash
# Clone and install deps
git clone https://github.com/Haidy-ID/golem-mcp
cd golem-mcp
uv sync

# Run MCP server standalone
uv run golem-mcp

# Install with local dev server
uv run golem-mcp install /path/to/project --local .

# Run coherence validator
python package/tools/validate_skills.py

# Run pre-flight (test)
python package/tools/preflight.py "add patrol enemy"
```

## License

MIT
