Godot MCP Unified - Arquitectura IA + Godot

Documentación para mi yo del futuro - Configuración completa para programar en lenguaje natural dentro de Godot

Leer en inglés

Arquitectura Global

                    +------------------+
                    |   Claude Code    |
                    |    (VS Code)     |
                    +--------+---------+
                             |
                             v
+----------------+  +--------+---------+  +------------------+
| Claude Desktop |->|                  |<-| ollmcp (Ollama)  |
|   (Anthropic)  |  | godot-mcp-unified|  | qwen2.5-coder:7b |
+----------------+  |   (ce serveur)   |  +------------------+
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
              v                             v
     +--------+---------+          +--------+---------+
     |  Godot CLI       |          |  Plugin WebSocket|
     |  (--headless)    |          |  (addons/godot_  |
     |  Fallback mode   |          |   mcp/) Port 6505|
     +------------------+          +------------------+
              |                             |
              +-------------+---------------+
                            |
                            v
                   +--------+---------+
                   |  Godot Engine    |
                   |    4.5.1         |
                   +------------------+

Comunicación con Godot

El servidor detecta automáticamente si el plugin está conectado y utiliza el modo óptimo.

Lo que permite hacer este servidor

HACER TODO en Godot en lenguaje natural (83 herramientas + 20 recursos + 20 prompts):

Instalación (ya realizado)

Requisitos instalados

• Node.js (para el servidor MCP)

• Godot 4.5.1: C:\Dev\Godot_v4.5.1-stable_win64.exe\Godot_v4.5.1-stable_win64_console.exe

• uv (gestor de Python moderno)

• ollmcp (puente Ollama <-> MCP)

Este servidor

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

Configuración

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 en tu proyecto 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 (vía ollmcp)

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

# Ou via ollama-gateway (port 3010)

Modelos Ollama disponibles

Nota: Los modelos -chess NO son para jugar al ajedrez, sino asistentes personalizados para el desarrollo de chess-app con system prompts FFE.

Referencia de API (83 herramientas + 20 recursos + 20 prompts)

Estadísticas

Primitives MCP:
  Tools:     83/83   ████████████████████ 100%
  Resources: 20/20   ████████████████████ 100%
  Prompts:   20/20   ████████████████████ 100%

Qualite:
  Tests:    3170+    ████████████████████ 100% pass (69 suites)
  Coverage:  85%     █████████████████░░░  85%

Bridge Plugin:
  Avec bridge:  47 outils (utilisent WebSocket si plugin actif)
  Sans bridge:  35 outils (CLI/file I/O uniquement)

Gestión de proyectos (14 herramientas)

• launch_editor - Abrir el editor Godot

• run_project - Ejecutar un proyecto

• stop_project - Detener el proyecto

• list_projects - Listar proyectos en una carpeta

• get_project_info - Información sobre un proyecto

• get_godot_version - Versión de Godot

• get_project_settings - Leer los ajustes del proyecto

• set_project_setting - Modificar un ajuste

• manage_input_actions - Gestionar acciones de entrada

• manage_autoloads - Gestionar autoloads

• validate_project - Validar la estructura del proyecto

• convert_project - Convertir proyecto Godot 3 a 4

• validate_conversion - Validar una conversión

• generate_docs - Generar documentación GDScript

Gestión de escenas (15 herramientas)

• create_scene - Crear una nueva escena

• add_node - Añadir un nodo

• edit_node - Modificar las propiedades de un nodo

• remove_node - Eliminar un nodo

• rename_node - Renombrar un nodo

• move_node - Mover un nodo (reparentar)

• duplicate_node - Duplicar un nodo

• load_sprite - Cargar una textura

• save_scene - Guardar una escena

• instance_scene - Instanciar una escena

• list_scenes - Listar escenas

• get_node_tree - Obtener el árbol de escenas

• connect_signal - Conectar una señal

• manage_groups - Gestionar grupos de nodos

• export_mesh_library - Exportar a MeshLibrary

Scripts GDScript (7 herramientas)

• list_scripts - Listar todos los .gd del proyecto

• read_script - Leer el contenido de un script

• write_script - Crear/modificar un script

• delete_script - Eliminar un script

• attach_script - Adjuntar script a un nodo

• detach_script - Desadjuntar script de un nodo

• get_script_errors - Errores de compilación

Animación (7 herramientas)

• create_animation_player - Crear AnimationPlayer

• add_animation - Añadir animación

• add_animation_track - Añadir track (valor, posición, rotación, etc.)

• set_keyframe - Definir keyframe con transición/easing

• create_animation_tree - Crear AnimationTree

• setup_state_machine - Configurar máquina de estados

• blend_animations - Configurar mezcla de animaciones

Física (3 herramientas)

• create_collision_shape - Crear CollisionShape2D/3D

• setup_rigidbody - Configurar RigidBody (masa, gravedad)

• configure_physics_layers - Nombrar capas físicas 2D/3D

TileMap (5 herramientas)

• create_tileset - Crear TileSet con tamaño de tile

• create_tilemap_layer - Crear TileMapLayer

• set_tile - Colocar un tile

• paint_tiles - Pintar tiles en lote

• import_ldtk_level - Importar nivel LDtk

Audio (3 herramientas)

• create_audio_bus - Crear bus de audio

• setup_audio_player - Configurar AudioStreamPlayer

• add_audio_effect - Añadir efecto (reverb, delay, eq)

Shader (2 herramientas)

• create_shader - Crear archivo .gdshader

• create_shader_material - Crear ShaderMaterial

Navegación (2 herramientas)

• create_navigation_region - Crear NavigationRegion2D/3D

• bake_navigation_mesh - Hornear navmesh

Partículas (2 herramientas)

• create_gpu_particles - Crear GPUParticles2D/3D

• create_particle_material - Crear ParticleProcessMaterial

UI (2 herramientas)

• create_ui_container - Crear contenedor (VBox, HBox, Grid, etc.)

• create_control - Crear control (Button, Label, etc.)

Iluminación (3 herramientas)

• create_light - Crear luz 2D/3D (Directional, Omni, Spot)

• setup_environment - Configurar entorno (niebla, resplandor, SSAO)

• setup_lightmapper - Configurar LightmapGI y horneado

Activos (3 herramientas)

• list_assets - Listar activos (imágenes, audio, modelos)

• import_asset - Importar archivo externo

• reimport_assets - Forzar reimportación

Exportación (3 herramientas)

• export_project - Exportar el proyecto

• export_pack - Exportar solo PCK

• list_export_presets - Listar presets de exportación

Operaciones en lote (1 herramienta)

• batch_operations - Ejecutar varias herramientas MCP en secuencia

Depuración (5 herramientas)

• get_debug_output - Recuperar la salida de consola

• start_debug_stream - Iniciar servidor WebSocket de depuración

• stop_debug_stream - Detener servidor WebSocket

• get_debug_stream_status - Estado del servidor

• take_screenshot - Capturar una captura de pantalla

UID (Godot 4.4+) (2 herramientas)

• get_uid - Obtener el UID de un archivo

• update_project_uids - Actualizar las referencias

Sistema (2 herramientas)

• system_health - Verificación de salud del sistema

• get_godot_version - Versión de Godot

Ejemplos de uso

Crear un personaje jugador

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

Depurar un proyecto

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

Modificar una escena existente

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

Estructura de los proyectos 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

Origen del código

Este servidor unifica las funcionalidades de 3 proyectos de código abierto:

Nota: GDAI MCP existe pero es de pago ($19).

Especificaciones de la máquina

• CPU: Ryzen 5 5600H

• RAM: 16 GB

• GPU: AMD Radeon (integrada) - sin CUDA

• Cuantización óptima: Q4_K_M (punto óptimo de calidad/rendimiento)

Solución de problemas

El servidor no arranca

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

Godot no encontrado

Verificar que GODOT_PATH apunte al ejecutable correcto (versión consola para ver los registros).

Claude Desktop no ve las herramientas

Reiniciar Claude Desktop después de modificar la configuración.

Comandos útiles

# 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

• [ ] Configurar git remote para jdvlh-godot-client

• [ ] Limpiar modelos Ollama redundantes (qwen2.5, gemma2, llama3.2, deepseek-coder-v2)

• [ ] Probar la integración completa con un nuevo proyecto

Última actualización: 11 de febrero de 2026 godot-mcp-unified v0.9.0 - 83 herramientas + 20 recursos + 20 prompts Cobertura: 85% | Pruebas: 3170+ (69 suites) | Cumple con ISO 25010/29119/5055/27001