golem-mcp 3.0.0
MCP bridge — connects AI coding agents to Godot 4.x via TCP
Requires Python: >=3.11
Keywords: ai, anthropic, claude, gamedev, godot, mcp

# Golem MCP — AI Bridge for Godot 4.x

**v3.0.0**

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
- **10 Commands** — `/think`, `/fix`, `/build`, `/learn`, `/ship`, `/init`, `/catchup`, `/checkpoint`, `/deliverable`, `/references`
- **3 Agents** — Builder (build, fix, deliverable), Designer (think, init), Maintainer (ship, catchup, checkpoint, learn, references)
- **10 Workflows** — Structured step-by-step sequences with `[C] Continue` gates for user control
- **10 Knowledge files** — Expert reference docs loaded JIT (architecture, UI, game feel, VFX, audio, camera, save, scene, theme)
- **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
- **21 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, `_golem/` module (agents, workflows, knowledge, recipes, references, tools), commands, rules, hooks, 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

# 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. Golem Module & Commands

Copy `_golem/` at project root and commands/rules/hooks into `.claude/`:

```
your-project/
  _golem/          <- package/_golem/ (agents, workflows, knowledge, recipes, references, tools)
  .claude/
    commands/      <- package/commands/*.md
    rules/         <- package/rules/*.md
    hooks/         <- package/hooks/*.py
```

</details>

### What gets installed

```
your-project/
├── addons/golem-mcp/          # Godot plugin (TCP server + handlers)
├── _golem/                    # Golem module (all AI knowledge & workflows)
│   ├── agents/                # 3 agent personas (builder, designer, maintainer)
│   ├── workflows/             # 10 workflows with sequential steps
│   ├── knowledge/             # 10 expert reference docs (loaded JIT)
│   ├── recipes/               # 21 tested implementation techniques
│   ├── references/            # GDScript pitfalls, workflow patterns
│   ├── tools/                 # Pre-flight and validation scripts
│   ├── agents-sub/            # 3 sub-agent definitions
│   └── config.yaml            # Project config
├── .claude/
│   ├── commands/              # 10 thin command pointers
│   ├── rules/                 # 7 auto-loaded rules (by glob pattern)
│   ├── hooks/                 # 5 Python hooks
│   └── settings.json          # Hook configuration
├── .mcp.json                  # MCP server config
└── CLAUDE.md                  # Project context for the AI agent
```

## Architecture

### Dispatch chain (V3 — BMAD-inspired)

```
/build "add patrol enemy"                    ← user invokes command
  → _golem/agents/builder.md                 ← agent: persona + principles + menu
    → _golem/workflows/build/workflow.md      ← workflow: config + init
      → steps/01-preflight.md                ← step 1: recipe scan, pitfall scan
      → steps/02-manifest.md        [C]      ← step 2: write deliverable manifest
      → steps/03-implement.md       [C]      ← step 3: load knowledge, build
      → steps/04-review.md          [C]      ← step 4: GDScript review checklist
      → steps/05-validate.md        [C]      ← step 5: scene inspection, close
```

Each `[C]` is a gate — the agent stops and waits for the user to type `C` before proceeding.

### TCP Bridge

```
GolemServer (GDScript @tool, multi-client TCP :3571)
│   └─ _handlers{} ──→ 8 handler nodes (35 tools)
│
←── TCP/JSON lines (:3571, max 10 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

Slash commands — the entry points for all workflows. Each command is a thin pointer (<15 lines) that loads an agent and presents its menu.

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

## Agents

Three agent personas, each with principles and a menu:

| Agent | Role | Principles |
|-------|------|------------|
| **Builder** | Godot 4.x developer | Containers > positions manuelles, knowledge before coding, feeling first, juice is part of the deliverable |
| **Designer** | Game designer / architect | Feeling first, max 3 core mechanics for MVP, shippable > perfect |
| **Maintainer** | Curator / shipper | Never modify game code, factual and concise |

## Knowledge (loaded JIT)

Expert reference docs loaded by workflow steps when needed — not all at once:

| File | Domain |
|------|--------|
| `architecture.md` | Pseudo-ECS, EventBus, components, folder structure |
| `scene-building.md` | MCP tool sequences, node creation, scene manipulation |
| `ui-composition.md` | Containers, layout patterns, Game Board pattern |
| `ui-behavior.md` | State machines, tweens, focus, feedback loops |
| `theme-tokens.md` | Theme resource, design tokens, StyleBox patterns |
| `game-feel.md` | Screenshake, freeze, squash & stretch, hit effects |
| `vfx.md` | GPUParticles2D, shaders, lighting, WorldEnvironment |
| `audio.md` | Bus layout, music manager, SFX pool, spatial audio |
| `camera.md` | Smooth follow, zoom, limits, cinematic, parallax |
| `save-system.md` | Settings, game state, slots, migration |

### 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 loads the Builder agent, runs the build workflow: pre-flight (matches recipes, surfaces pitfalls, finds relevant project files), manifest, implementation with knowledge loading, review, and validation.

### 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 10 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 10 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/_golem/tools/validate_skills.py

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

# Run tests
uv run pytest
```

## License

MIT