golem-mcp 0.7.1

MCP bridge between Claude Code and Godot 4.x

Golem MCP

MCP open-source pour connecter Claude Code à Godot 4.x.

Claude Code ←stdio/MCP→ golem_mcp.py (FastMCP) ←TCP/JSON→ GolemServer (GDScript @tool)

Installation

Quick install (recommended)

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

This copies the plugin, skills, and generates .mcp.json automatically.

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

Options

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

Phase 1 — Core

Tool	Description
godot_get_scene_tree	Arbre de scène hiérarchique
godot_inspect_node	Propriétés d'un node
godot_get_editor_screenshot	Capture éditeur
godot_get_game_screenshot	Capture jeu en cours
godot_play_scene	Lancer une scène
godot_stop_scene	Stopper la scène
godot_get_errors	Récupérer erreurs
godot_clear_logs	Vider les logs
godot_execute_script	Exécuter GDScript dans l'éditeur
godot_view_script	Lire un script

Phase 2 — Manipulation

Tool	Description
godot_add_node	Créer un node
godot_delete_node	Supprimer un node
godot_update_property	Modifier une propriété
godot_move_node	Déplacer dans l'arbre
godot_duplicate_node	Dupliquer un node

Phase 3 — Avancé

Tool	Description
godot_get_input_map	Lire les actions input
godot_project_settings	Lire/modifier settings projet
godot_save_scene	Sauvegarder la scène

Phase 3 — Avancé (suite)

Tool	Description
godot_write_script	Écrire un fichier .gd
godot_attach_script	Attacher un script à un node
godot_get_logs	Logs jeu + engine
godot_create_scene	Créer une nouvelle scène
godot_open_scene	Ouvrir une scène existante
godot_add_nodes	Batch: créer une hiérarchie entière

Skills (slash commands)

Copier .claude/commands/*.md dans .claude/commands/ de ton projet Godot.

Workflow Commands

Skill	Rôle
/init	Bootstrap projet — vision, gameplay loop, livrables, structure (nouveau projet ou reprise)
/golem-dev	Mode MCP — switch contexte pour travailler sur Golem MCP lui-même
/deliverable <nom>	Focus livrable — implémenter UN livrable jusqu'à complétion
/checkpoint	Snapshot état — scanner le projet, générer CHECKPOINT.md
/references	Patterns projet — voir/éditer les conventions réutilisables

Core Skills

Skill	Rôle
/godot	Routeur principal — analyse l'intention, scanne le projet, dispatche vers le bon skill
/godot-plan	Interroger l'idée, produire un mini-PRD + plan séquencé avant toute construction
/godot-architecture	Architecture modulaire pseudo-ECS : Core, Entities, Mechanics, Data
/godot-scene	Construire une scène Godot à partir d'une description
/godot-composition	Structure UI : tokens, rôles, containers, patterns, torture tests
/godot-behavior	Système nerveux UI : états 3 canaux, tweens, FX, son, fallback perf
/godot-theme	Design tokens via Theme resource : palette, fonts, spacing, StyleBox
/godot-debug	Diagnostic séquentiel en 5 étapes + table des bugs courants
/godot-design-audit	Audit UX via screenshots + inspection, rapport phasé d'améliorations
/godot-status	Scan projet, DEVLOG.md, progress.txt, suggestions d'amélioration

Hooks

Golem MCP fournit 4 hooks Claude Code dans hooks/ (Python, cross-platform) :

Hook	Event	Rôle
check_connection.py	PreToolUse (godot_*)	Vérifie la connexion TCP avant chaque appel MCP
gdscript_lint.py	PostToolUse (godot_write_script)	Lint basique GDScript après écriture
copy_skills.py	PostToolUse (Edit/Write)	Auto-copie les skills modifiés vers le projet test (dev)
check_project_sync.py	PostToolUse (Edit/Write)	Sync livrables, checkpoint, références

Installation dans ton projet Godot

Copier le template et adapter les paths :

cp hooks/settings.example.json ton-projet/.claude/settings.json
# Éditer les paths dans le fichier

Ou ajouter manuellement dans .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "mcp__godot__.*",
      "hooks": [{"type": "command", "command": "python3 /chemin/vers/golem-mcp/hooks/check_connection.py", "timeout": 3}]
    }],
    "PostToolUse": [{
      "matcher": "mcp__godot__godot_write_script",
      "hooks": [{"type": "command", "command": "python3 /chemin/vers/golem-mcp/hooks/gdscript_lint.py", "timeout": 5}]
    }]
  }
}

Workflow recommandé

Nouveau projet (complet)

/init → /deliverable <premier> → /checkpoint → /deliverable <suivant> → ...

1. /init — Bootstrap complet : vision, gameplay loop, vertical slice, livrables, structure
2. /deliverable <nom> — Implémenter UN livrable jusqu'à complétion
3. /checkpoint — Snapshot état, valider les progrès
4. Répéter jusqu'au vertical slice complet

Reprise de projet

/init (détecte l'état) → /checkpoint → /deliverable <en_cours>

/init détecte automatiquement les fichiers existants et propose de reprendre.

Travailler sur Golem MCP

/golem-dev

Switch de contexte pour modifier le MCP lui-même. Revenir avec /init ou tout skill Godot.

Workflow classique (sans livrables)

/godot-plan  →  /godot-architecture  →  /godot-scene  →  /godot-theme  →  /godot-status

1. /godot-plan — Définir la vision, les mécaniques, le feeling visé. Produit GAME_PLAN.md
2. /godot-architecture — Scaffolder Core (EventBus, GameState), structure dossiers
3. /godot-scene — Construire les scènes une par une selon le plan
4. /godot-theme — Design system si UI (palette, fonts, StyleBox)
5. /godot-status — Documenter l'état du projet (DEVLOG.md, progress.txt)

Construire une UI

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

La structure (containers, tokens, rôles) AVANT le thème AVANT le behavior (animations, états).

Debug

/godot-debug  →  fix  →  /godot-status

Route directe — pas de prérequis.

Prototypage rapide

/godot-scene  (mode QUICK, sans plan ni archi)

Pour tester une idée vite. Transition vers le flow complet si le proto marche.

Troubleshooting

"Connection refused" / Port non disponible

Symptôme : Le hook check_connection.py bloque avec "Godot n'est pas connecté"

Causes possibles :

1. Godot n'est pas ouvert
2. Le plugin Golem MCP n'est pas activé
3. Un autre process utilise le port 3571

Solutions :

# Vérifier si le port est utilisé
lsof -i :3571        # macOS/Linux
netstat -ano | findstr :3571  # Windows

# Changer de port (si conflit)
export GOLEM_PORT=3572  # Avant de lancer Claude Code

Dans Godot : Project > Project Settings > Plugins > Golem MCP doit être activé (checkbox cochée).

"No scene is currently running" (screenshot)

Symptôme : godot_get_game_screenshot retourne une erreur

Cause : Le jeu n'est pas lancé, ou la scène a crashé

Solution : Lancer le jeu avec godot_play_scene avant de capturer

Screenshot vide / erreur base64

Symptôme : "Screenshot file was empty or corrupted" ou erreur API "image cannot be empty"

Causes possibles :

1. GolemCapture autoload non injecté dans le jeu
2. Le jeu a crashé avant la capture
3. Race condition (capture trop rapide)

Solutions :

1. Vérifier que golem_capture.gd est bien copié dans addons/golem-mcp/
2. Le système retry automatiquement 3 fois — si ça échoue quand même, vérifier les logs Godot
3. Utiliser godot_get_errors pour voir si le jeu a crashé

Lint warnings après godot_write_script

Symptôme : Le hook gdscript_lint.py remonte des warnings

C'est normal — le lint est un filet de sécurité. Les warnings courants :

• Missing 'extends' — ajouter extends Node (ou le bon type)
• print() found — remplacer par GolemCapture.log() pour voir les logs via MCP
• await inside _process — interdit en @tool, utiliser un deferred pattern
• Camera2D position modified — utiliser offset au lieu de position pour le screenshake

Ghost connections dans les logs Godot

Symptôme : "Condition '!is_open()' is true" répété dans les logs

Cause : Connexions TCP fantômes (probes de port)

Solution : Déjà fixé dans v0.5.1 — le serveur ignore silencieusement ces connexions. Mettre à jour le plugin.

Protocole TCP

JSON lines sur port 3571 (configurable via GOLEM_PORT).

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

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

Licence

MIT