golem-mcp 3.0.0

MCP bridge — connects AI coding agents to Godot 4.x via TCP

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

# 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)

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

# 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

If you prefer to install manually

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

cd golem-mcp
uv sync

3. Claude Code Config

Create .mcp.json at your project root:

{
  "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

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

# 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

# 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