Godot MCP

                           (((((((             (((((((                          
                        (((((((((((           (((((((((((                      
                        (((((((((((((       (((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
         (((((      (((((((((((((((((((((((((((((((((((((((((      (((((        
       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((      
     ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
    ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((     
        (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((       
         (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((        
         (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((        
         ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@        
         ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((        
         (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((        
          (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((         
           (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((          
              (((((((((((((((((((((((((((((((((((((((((((((((((((((             
                 (((((((((((((((((((((((((((((((((((((((((((((((                
                        (((((((((((((((((((((((((((((((((                       
                                                                                

                          /$$      /$$  /$$$$$$  /$$$$$$$ 
                         | $$$    /$$$ /$$__  $$| $$__  $$
                         | $$$$  /$$$$| $$  \__/| $$  \ $$
                         | $$ $$/$$ $$| $$      | $$$$$$$/
                         | $$  $$$| $$| $$      | $$____/ 
                         | $$\  $ | $$| $$    $$| $$      
                         | $$ \/  | $$|  $$$$$$/| $$      
                         |__/     |__/ \______/ |__/       

Un servidor de Protocolo de Contexto de Modelo (MCP) para interactuar con el motor de juego Godot.

Introducción

Godot MCP permite a los asistentes de IA iniciar el editor Godot, ejecutar proyectos, capturar resultados de depuración y controlar la ejecución del proyecto, todo a través de una interfaz estandarizada.

Este ciclo de retroalimentación directa ayuda a los asistentes de IA como Claude a comprender qué funciona y qué no en proyectos reales de Godot, lo que conduce a una mejor generación de código y asistencia en la depuración.

Características

Iniciar el editor Godot : abre el editor Godot para un proyecto específico
Ejecutar proyectos Godot : ejecutar proyectos Godot en modo de depuración
Capturar salida de depuración : recuperar la salida de la consola y los mensajes de error
Ejecución de control : iniciar y detener proyectos Godot mediante programación
Obtener la versión de Godot : recupera la versión de Godot instalada
Lista de proyectos de Godot : busca proyectos de Godot en un directorio específico
Análisis del proyecto : Obtenga información detallada sobre la estructura del proyecto
Gestión de escenas :
- Crear nuevas escenas con tipos de nodos raíz específicos
- Agregue nodos a escenas existentes con propiedades personalizables
- Cargar sprites y texturas en nodos Sprite2D
- Exportar escenas 3D como recursos de MeshLibrary para GridMap
- Guardar escenas con opciones para crear variantes
Gestión de UID (para Godot 4.4+):
- Obtener UID para archivos específicos
- Actualizar referencias de UID volviendo a guardar recursos

Requisitos

Godot Engine instalado en su sistema
Node.js y npm
Un asistente de IA que admite MCP (Cline, Cursor, etc.)

Instalación y configuración

Paso 1: Instalar y compilar

Primero, clone el repositorio y construya el servidor MCP:

git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp
npm install
npm run build

Paso 2: Configura con tu asistente de IA

Opción A: Configurar con Cline

Agregue a su archivo de configuración de Cline MCP ( ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ):

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // Optional: Enable detailed logging
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

Opción B: Configurar con cursor

Usando la interfaz de usuario del cursor:

Vaya a Configuración del cursor > Funciones > MCP
Haga clic en el botón + Agregar nuevo servidor MCP
Rellene el formulario:
- Nombre: godot (o cualquier nombre que prefieras)
- Tipo: command
- Comando: node /absolute/path/to/godot-mcp/build/index.js
Haga clic en "Agregar"
Es posible que deba presionar el botón de actualización en la esquina superior derecha de la tarjeta del servidor MCP para completar la lista de herramientas

Uso de la configuración específica del proyecto:

Crea un archivo en .cursor/mcp.json en el directorio de tu proyecto con el siguiente contenido:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // Enable detailed logging
      }
    }
  }
}

Paso 3: Variables de entorno opcionales

Puede personalizar el comportamiento del servidor con estas variables de entorno:

GODOT_PATH : Ruta al ejecutable de Godot (anula la detección automática)
DEBUG : Establezca en "verdadero" para habilitar el registro de depuración detallado del lado del servidor

Ejemplos de indicaciones

Una vez configurado, tu asistente de IA ejecutará automáticamente el servidor MCP cuando sea necesario. Puedes usar indicaciones como:

"Launch the Godot editor for my project at /path/to/project"

"Run my Godot project and show me any errors"

"Get information about my Godot project structure"

"Analyze my Godot project structure and suggest improvements"

"Help me debug this error in my Godot project: [paste error]"

"Write a GDScript for a character controller with double jump and wall sliding"

"Create a new scene with a Player node in my Godot project"

"Add a Sprite2D node to my player scene and load the character texture"

"Export my 3D models as a MeshLibrary for use with GridMap"

"Create a UI scene with buttons and labels for my game's main menu"

"Get the UID for a specific script file in my Godot 4.4 project"

"Update UID references in my Godot project after upgrading to 4.4"

Detalles de implementación

Arquitectura

El servidor Godot MCP utiliza un enfoque GDScript integrado para operaciones complejas:

Comandos directos : operaciones simples como iniciar el editor u obtener información del proyecto utilizan directamente los comandos CLI integrados de Godot.
Script de operaciones agrupadas : las operaciones complejas, como crear escenas o agregar nodos, utilizan un único archivo GDScript completo ( godot_operations.gd ) que maneja todas las operaciones.

Esta arquitectura ofrece varias ventajas:

Sin archivos temporales : elimina la necesidad de archivos de script temporales, manteniendo su sistema limpio
Base de código simplificada : centraliza todas las operaciones de Godot en un archivo (algo) organizado
Mejor mantenibilidad : facilita agregar nuevas operaciones o modificar las existentes.
Manejo de errores mejorado : proporciona informes de errores consistentes en todas las operaciones
Gastos generales reducidos : minimiza las operaciones de E/S de archivos para un mejor rendimiento

El script incluido acepta el tipo de operación y los parámetros como JSON, lo que permite una ejecución de operaciones flexible y dinámica sin generar archivos temporales para cada operación.

Solución de problemas

Godot no encontrado : Establezca la variable de entorno GODOT_PATH en su ejecutable Godot
Problemas de conexión : asegúrese de que el servidor esté funcionando y reinicie su asistente de IA
Ruta de proyecto no válida : asegúrese de que la ruta apunte a un directorio que contenga un archivo project.godot
Problemas de compilación : asegúrese de que todas las dependencias estén instaladas ejecutando npm install
Para el cursor específicamente :
Asegúrese de que el servidor MCP aparezca y esté habilitado en la configuración del cursor (Configuración > MCP)
Las herramientas MCP solo se pueden ejecutar utilizando el perfil de chat del Agente (suscripción Cursor Pro o Business)
Utilice el "Modo Yolo" para ejecutar automáticamente las solicitudes de herramientas MCP

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Integrations