golem-mcp 2.3.0

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

Golem MCP — AI Bridge for Godot 4.x

v2.3.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
• 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

# 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, commands, skills, rules, hooks, recipes, references, 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

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

# 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. 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/

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

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

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

License

MIT