Godot MCP Unified - Architecture IA + Godot

Documentation pour mon futur moi - Configuration complete pour coder en langage naturel dans Godot

Read in English

Architecture Globale

                    +------------------+
                    |   Claude Code    |
                    |    (VS Code)     |
                    +--------+---------+
                             |
                             v
+----------------+  +--------+---------+  +------------------+
| Claude Desktop |->|                  |<-| ollmcp (Ollama)  |
|   (Anthropic)  |  | godot-mcp-unified|  | qwen2.5-coder:7b |
+----------------+  |   (ce serveur)   |  +------------------+
                    +--------+---------+
                             |
                             v
                    +--------+---------+
                    |  Godot Engine    |
                    |    4.5.1         |
                    +------------------+

Ce que ce serveur permet de faire

TOUT faire dans Godot en langage naturel (76 outils) :

Fonctionnalite	Description	Exemple
Scripts CRUD	Creer/lire/modifier/supprimer des scripts GDScript	"Cree un script de mouvement pour le joueur"
Scenes	Creer et modifier des scenes .tscn	"Cree une scene Player avec CharacterBody2D"
Nodes	Ajouter/modifier/supprimer des nodes	"Ajoute un Sprite2D au Player"
Animation	AnimationPlayer, tracks, keyframes	"Cree une animation de marche avec 4 frames"
Physics	Collision shapes, rigidbody, layers	"Configure la physique du joueur"
TileMap	TileSet, TileMapLayer, placement tuiles	"Cree une tilemap avec les tuiles de terrain"
Audio	Bus audio, players, effets	"Ajoute un reverb au bus Master"
Shaders	Creer shaders et materials	"Cree un shader de dissolution"
Navigation	Regions et navmesh	"Configure la navigation pour l'IA"
Particles	GPU particles et materials	"Ajoute des particules de feu"
UI	Containers et controls	"Cree un menu principal"
Lighting	Lumieres 2D/3D et environment	"Configure l'eclairage du niveau"
Assets	Import, liste, reimport	"Importe les textures du dossier assets"
Export	Presets, export projet/PCK	"Liste les presets d'export"
Batch	Operations en sequence	"Execute ces 5 operations d'affilee"
Debug	Stream temps reel WebSocket	"Demarre le stream debug sur port 9999"
UID	Gestion des identifiants Godot 4.4+	"Mets a jour les references UID"
3D	Export MeshLibrary pour GridMap	"Exporte les meshes en MeshLibrary"

Installation (deja fait)

Prerequis installes

• Node.js (pour le serveur MCP)
• Godot 4.5.1 : C:\Dev\Godot_v4.5.1-stable_win64.exe\Godot_v4.5.1-stable_win64_console.exe
• uv (gestionnaire Python moderne)
• ollmcp (bridge Ollama <-> MCP)

Ce serveur

cd C:\Dev\godot-mcp-unified
npm install
npm run build

Configuration

Claude Desktop (C:\Users\pierr\AppData\Roaming\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

VS Code / Claude Code (.vscode/mcp.json dans ton projet Godot)

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

Ollama (via ollmcp)

# Lancer le bridge
ollmcp --model qwen2.5-coder:7b C:\Dev\godot-mcp-unified\build\index.js

# Ou via ollama-gateway (port 3010)

Modeles Ollama disponibles

Modele	Taille	Usage
qwen2.5-coder:7b	4.7 GB	Principal pour GDScript - 88.4% HumanEval
mistral:latest	4.4 GB	Narration pour jdvlh-ia-game
gemma2-chess:latest	5.4 GB	Expert FFE pour chess-app
qwen2.5-chess:latest	4.7 GB	Tool calling pour chess-app
llama3.2-chess:latest	2.0 GB	Tool calling leger pour chess-app
deepseek-chess:latest	8.9 GB	Architecture pour chess-app

Note: Les modeles -chess ne sont PAS pour jouer aux echecs mais des assistants personnalises pour le developpement de chess-app avec system prompts FFE.

API Reference (76 outils disponibles)

Gestion de projet (12 outils)

• launch_editor - Ouvrir l'editeur Godot
• run_project - Lancer un projet
• stop_project - Arreter le projet
• get_debug_output - Recuperer la sortie console
• list_projects - Lister les projets dans un dossier
• get_project_info - Info sur un projet
• get_godot_version - Version de Godot
• get_project_settings - Lire les settings du projet
• set_project_setting - Modifier un setting
• get_input_map - Lire la map des inputs
• add_input_action - Ajouter une action input
• validate_project - Valider la structure projet

Gestion des scenes (10 outils)

• create_scene - Creer une nouvelle scene
• add_node - Ajouter un node
• edit_node - Modifier les proprietes d'un node
• remove_node - Supprimer un node
• rename_node - Renommer un node
• move_node - Deplacer un node (reparent)
• duplicate_node - Dupliquer un node
• load_sprite - Charger une texture
• save_scene - Sauvegarder une scene
• get_scene_tree - Obtenir l'arbre de scene

Scripts GDScript (6 outils)

• list_scripts - Lister tous les .gd du projet
• read_script - Lire le contenu d'un script
• write_script - Creer/modifier un script
• attach_script - Attacher script a un node
• detach_script - Detacher script d'un node
• get_script_errors - Erreurs de compilation

Animation (4 outils)

• create_animation_player - Creer AnimationPlayer
• add_animation - Ajouter animation
• add_animation_track - Ajouter track (value, position, rotation, etc.)
• set_keyframe - Definir keyframe avec transition/easing

Physics (3 outils)

• create_collision_shape - Creer CollisionShape2D/3D
• setup_rigidbody - Configurer RigidBody (masse, gravite)
• configure_physics_layers - Nommer layers physique 2D/3D

TileMap (4 outils)

• create_tileset - Creer TileSet avec tile size
• create_tilemap_layer - Creer TileMapLayer
• set_tile - Placer une tuile
• paint_tiles - Peindre tuiles en batch

Audio (3 outils)

• create_audio_bus - Creer bus audio
• setup_audio_player - Configurer AudioStreamPlayer
• add_audio_effect - Ajouter effet (reverb, delay, eq)

Shader (2 outils)

• create_shader - Creer fichier .gdshader
• create_shader_material - Creer ShaderMaterial

Navigation (2 outils)

• create_navigation_region - Creer NavigationRegion2D/3D
• bake_navigation_mesh - Cuire navmesh

Particles (2 outils)

• create_gpu_particles - Creer GPUParticles2D/3D
• create_particle_material - Creer ParticleProcessMaterial

UI (2 outils)

• create_ui_container - Creer Container (VBox, HBox, Grid, etc.)
• create_control - Creer Control (Button, Label, etc.)

Lighting (2 outils)

• create_light - Creer Light2D/3D (Directional, Omni, Spot)
• setup_environment - Configurer Environment (fog, glow, SSAO)

Assets (3 outils)

• list_assets - Lister assets (images, audio, modeles)
• import_asset - Importer fichier externe
• reimport_assets - Forcer reimport

Export (3 outils)

• export_project - Exporter le projet
• export_pack - Exporter PCK seul
• list_export_presets - Lister presets export

Batch Operations (1 outil)

• batch_operations - Executer plusieurs outils MCP en sequence

Debug Stream (3 outils)

• start_debug_stream - Demarrer serveur WebSocket debug
• stop_debug_stream - Arreter serveur WebSocket
• get_debug_stream_status - Statut du serveur

UID (Godot 4.4+)

• get_uid - Obtenir l'UID d'un fichier
• update_project_uids - Mettre a jour les references

3D

• export_mesh_library - Exporter en MeshLibrary

Exemples d'utilisation

Creer un personnage joueur

"Cree une scene Player.tscn avec un CharacterBody2D comme root,
ajoute un Sprite2D nomme 'Sprite' et un CollisionShape2D nomme 'Collision'"

Debugger un projet

"Lance mon projet Godot et montre-moi les erreurs dans la console"

Modifier une scene existante

"Dans la scene Player.tscn, change la position du Sprite a (100, 50)
et sa scale a 2x"

Structure des projets Godot

C:\Dev\
├── jdvlh-godot-client\     <- Projet principal (pas de remote git configure!)
│   ├── project.godot
│   ├── .vscode\mcp.json    <- Config MCP pour ce projet
│   └── addons\godot_mcp\   <- Plugin MCP copie
│
├── jdvlh-godot\            <- Projet vide (a garder pour tests)
│
└── GodotDynamicDialog\     <- Fork de dynamic-dialog

Origine du code

Ce serveur unifie les fonctionnalites de 3 projets open-source :

Projet	Fonctionnalites	Repo
ee0pdt/Godot-MCP	Scripts CRUD	https://github.com/ee0pdt/Godot-MCP
bradypp/godot-mcp	Base principale - Scenes, nodes, UID, 3D	https://github.com/bradypp/godot-mcp
Coding-Solo/godot-mcp	Launch, run, debug	https://github.com/Coding-Solo/godot-mcp

Note: GDAI MCP existe mais est payant ($19).

Specs machine

• CPU: Ryzen 5 5600H
• RAM: 16 GB
• GPU: AMD Radeon (integre) - pas de CUDA
• Quantization optimale: Q4_K_M (sweet spot qualite/performance)

Troubleshooting

Le serveur ne demarre pas

cd C:\Dev\godot-mcp-unified
npm run build

Godot non trouve

Verifier que GODOT_PATH pointe vers le bon executable (version console pour voir les logs).

Claude Desktop ne voit pas les outils

Redemarrer Claude Desktop apres modification de la config.

Commandes utiles

# Rebuild le serveur
cd C:\Dev\godot-mcp-unified && npm run build

# Tester avec l'inspecteur MCP
npm run inspector

# Lister les modeles Ollama
ollama list

# Supprimer un modele Ollama
ollama rm nom_modele

TODO

• [ ] Configurer git remote pour jdvlh-godot-client
• [ ] Nettoyer les modeles Ollama redondants (qwen2.5, gemma2, llama3.2, deepseek-coder-v2)
• [ ] Tester l'integration complete avec un nouveau projet

---

Derniere mise a jour: Decembre 2024 godot-mcp-unified v0.8.0 - 76 outils