golem-mcp 2.0.0

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

Golem — AI Assistant for Godot 4.x

v0.13.0

Build Godot games with AI. Chat dock in the editor + MCP bridge for Claude Code. BYOK — your model, your key, no subscription.

Features

• Chat Dock — Agent loop with streaming, tool calling, conversation persistence, right inside the Godot editor
• 26 Tools — Scenes, scripts, screenshots, input simulation, project settings, node manipulation…
• MCP Bridge — Works with Claude Code, Cursor, Windsurf, Continue.dev, Cline via TCP
• BYOK Multi-Provider — OpenAI, OpenRouter, Ollama, Gemini, or any OpenAI-compatible endpoint
• 25 Expert Skills — Slash commands for Claude Code (plan, build, debug, test, audit…)
• 7 Hooks — Auto-lint, connection check, .tscn protection, context restore after compaction
• Auto-Updates — GitHub Releases check every 24h, one-click update in the editor

Quick Start

Chat Dock (recommended)

1. Install: uvx golem-mcp install /path/to/your/godot-project
2. Enable plugin: Godot > Project Settings > Plugins > Golem MCP
3. Open the Golem dock → enter your API key in Settings → chat

MCP Bridge (Claude Code / Cursor / Windsurf)

1. Install: uvx golem-mcp install /path/to/your/godot-project
2. Enable plugin: Godot > Project Settings > Plugins > Golem MCP
3. Open your project in Claude Code → type /godot

Installation

Option 1 — CLI (recommended)

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

This copies the plugin, skills, hooks, and generates configs automatically.

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

Option 2 — ZIP Installer

1. Download the latest .zip from releases
2. Extract and run install.bat (Windows) or ./install.sh (macOS/Linux)
3. Enter your Godot project path
4. Enable the plugin in Godot

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 instead of uvx (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

Manual installation

If you prefer to install manually

1. Plugin Godot

Copier le dossier godot-plugin/ dans ton projet Godot :

ton-projet/addons/golem-mcp/ ← contenu de godot-plugin/

Activer le plugin : Project > Project Settings > Plugins > Golem MCP

2. Serveur MCP Python

cd golem-mcp
uv sync

3. Configuration Claude Code

Créer un .mcp.json à la racine de ton projet Godot :

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

Auto-updates

The plugin checks for updates every 24h via GitHub Releases. When a new version is available, you'll get a dialog in the Godot editor to update in one click.

Tools (26)

Available in both the Chat Dock (tool calling) and MCP Bridge (Claude Code tools).

Tool	Description
godot_get_scene_tree	Scene tree hierarchy (detail_level: full/summary)
godot_inspect_node	Node properties, signals, groups (detail_level: full/summary)
godot_get_editor_screenshot	Editor viewport capture
godot_get_game_screenshot	Running game capture
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
godot_view_script	Read a script
godot_add_node	Create a 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_get_input_map	Read input actions
godot_project_settings	Read/write project settings
godot_project_context	Full project dump (settings, autoloads, input map, files)
godot_save_scene	Save the current scene
godot_write_script	Write a .gd file
godot_attach_script	Attach a script to a node
godot_get_logs	Game + engine logs (incremental)
godot_create_scene	Create a new scene
godot_open_scene	Open an existing scene
godot_add_nodes	Batch: create a full node hierarchy
godot_find_nodes	Search nodes by type, group, name, script
godot_simulate_input	Simulate input sequences in the running game

Skills (25, MCP Bridge only)

Slash commands for Claude Code / Cursor / Windsurf. The Chat Dock uses tools directly with dynamic system prompts.

Workflow Commands

Skill	Role
/init	Bootstrap a new project (vision → deliverables → structure)
/golem-dev	Switch context to work on Golem MCP itself
/deliverable <name>	Focus on a specific deliverable until completion
/checkpoint	Snapshot project state into CHECKPOINT.md
/references	Extract reusable patterns from the project

Planning & Simulation

Skill	Role
/godot	Router — dispatches to the right skill based on intent
/godot-plan	Plan a feature — interrogate, structure, produce a mini-PRD
/godot-sequence	Define game flow as YAML (loops, states, emotional arc)
/godot-simulate	Paper-prototype a sequence (friction, balance, edge cases)
/godot-gate	Validate readiness before construction (auto-checks + questions)

Construction

Skill	Role
/godot-architecture	Design modular architecture (EventBus, components, scripts)
/godot-scene	Build a Godot scene via MCP tools
/godot-composition	Structure UI (tokens, containers, layout, torture tests)
/godot-theme	Create a design token system via Theme resource
/godot-behavior	Add states, transitions, tweens and feedback loops to UI

Game Feel, VFX & Audio

Skill	Role
/godot-juice	Add game feel (screenshake, freeze, squash, hit effects)
/godot-vfx	Create visual effects (particles, shaders, lighting)
/godot-audio	Set up audio (bus, music manager, SFX pool, spatial)
/godot-save	Implement save/load (settings, game state, slots, migration)
/godot-camera	Configure 2D camera (follow, zoom, limits, cinematic)

Debug & Audit

Skill	Role
/godot-debug	Diagnose and fix issues step by step
/godot-test	Automated tests (input simulation + logs + verification)
/godot-design-audit	Audit UX via screenshots and produce a report
/godot-status	Scan project state, generate DEVLOG, track progress

Hooks

7 Claude Code hooks in hooks/ (Python, cross-platform):

Hook	Event	Role
check_connection.py	PreToolUse (godot_*)	Checks TCP connection before each MCP call
block_tscn_edit.py	PreToolUse (Edit/Write)	Blocks direct .tscn file editing
pre_compact.py	PreCompact	Saves project state before context compaction
gdscript_lint.py	PostToolUse (godot_write_script)	Lints GDScript after writing (+ := Variant detection)
copy_skills.py	PostToolUse (Edit/Write)	Auto-copies modified skills to test project (dev)
check_project_sync.py	PostToolUse (Edit/Write)	Syncs deliverables, checkpoint, references
compact_context.py	SessionStart (compact)	Restores project context after compaction

Installation in your Godot project

Copy the template and adjust paths:

cp hooks/settings.example.json your-project/.claude/settings.json
# Edit paths in the file

Or add manually in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__godot__.*",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/check_connection.py", "timeout": 3}]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/block_tscn_edit.py", "timeout": 3}]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/compact_context.py", "timeout": 5}]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/pre_compact.py", "timeout": 5}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "mcp__godot__godot_write_script",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/gdscript_lint.py", "timeout": 5}]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "python3 .claude/hooks/check_project_sync.py", "timeout": 3}]
      }
    ]
  }
}

Workflow

New project (full)

/init → /deliverable <first> → /checkpoint → /deliverable <next> → ...

1. /init — Full bootstrap: vision, gameplay loop, vertical slice, deliverables, structure
2. /deliverable <name> — Implement ONE deliverable until completion
3. /checkpoint — Snapshot state, validate progress
4. Repeat until vertical slice is complete

Resuming a project

/init (detects state) → /checkpoint → /deliverable <in_progress>

/init auto-detects existing files and offers to resume.

Working on Golem MCP itself

/golem-dev

Switches context to modify the MCP itself. Return with /init or any Godot skill.

Classic workflow (no deliverables)

/godot-plan → /godot-sequence → /godot-simulate → /godot-gate → /godot-architecture → /godot-scene

1. /godot-plan — Define the vision, mechanics, target feeling. Produces GAME_PLAN.md
2. /godot-sequence — Formalize game flow as YAML (loops, states, data)
3. /godot-simulate — Test the game on paper (3 modes: narrative, balance, exhaustive)
4. /godot-gate — Validate everything is ready before coding
5. /godot-architecture — Scaffold Core (EventBus, GameState), folder structure
6. /godot-scene — Build scenes one by one following the plan

Building UI

/godot-composition  →  /godot-theme  →  /godot-behavior

Structure (containers, tokens, roles) BEFORE theme BEFORE behavior (animations, states).

Debug

/godot-debug  →  fix  →  /godot-status

Direct route — no prerequisites.

Quick prototyping

/godot-scene  (QUICK mode, no plan or architecture)

For testing an idea fast. Transition to full flow if the prototype works.

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 (checkbox checked).

"No scene is currently running" (screenshot)

Symptom: godot_get_game_screenshot returns an error

Cause: The game is not running, or the scene crashed

Solution: Run the game with godot_play_scene before capturing

Empty screenshot / base64 error

Symptom: "Screenshot file was empty or corrupted" or API error "image cannot be empty"

Possible causes:

1. GolemCapture autoload not injected in the game
2. The game crashed before capture
3. Race condition (capture too fast)

Solutions:

1. Check that golem_capture.gd is copied in addons/golem-mcp/
2. The system retries automatically 3 times — if it still fails, check Godot logs
3. Use godot_get_errors to see if the game crashed

Lint warnings after godot_write_script

Symptom: The gdscript_lint.py hook reports warnings

This is normal — lint is a safety net. Common warnings:

• Missing 'extends' — add extends Node (or the correct type)
• print() found — replace with GolemCapture.game_log() to see logs via MCP
• await inside _process — forbidden in @tool, use a deferred pattern
• Camera2D position modified — use offset instead of position for screenshake
• ':=' with Variant source — replace := with : Type = when source is Array, Dict, ternary, .duplicate()

Ghost connections in Godot logs

Symptom: "Condition '!is_open()' is true" repeated in logs

Cause: Ghost TCP connections (port probes)

Solution: Fixed in v0.5.1 — the server silently ignores these connections. Update the plugin.

TCP Protocol

JSON lines on port 3571 (configurable via GOLEM_PORT).

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

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

License

MIT