Godot MCP

Más de 300 herramientas que conectan asistentes de IA directamente al editor de Godot. Crea escenas, escribe scripts, prueba el juego, todo mediante lenguaje natural.

GitHub
21
Prueba este MCPPatrocinado

Documentación

Godot MCP

Desarrollo de juegos impulsado por IA para Godot Engine mediante Model Context Protocol

TypeScript GDScript Godot 4.x MCP License: MIT

🌐 Sitio web · 📋 Catálogo de herramientas · 💬 GitHub · 📦 Lanzamientos

Godot MCP conecta asistentes de IA (Claude, Cursor, VS Code Copilot, OpenCode y cualquier cliente compatible con MCP) directamente al editor de Godot. Expone más de 300 herramientas en más de 40 módulos, cubriendo todo, desde la construcción de escenas y la manipulación de nodos hasta la inspección en tiempo de ejecución, la grabación de entrada, la configuración de física, la creación de animaciones, la exportación de proyectos, la gestión de complementos, la depuración y la configuración específica de la plataforma.

La IA puede leer tu árbol de escena, crear nodos, escribir scripts, simular entrada de juego, capturar capturas de pantalla, ejecutar aserciones y modificar propiedades en lote entre escenas, todo a través de un único puente WebSocket.

Este proyecto fue desarrollado con la ayuda de múltiples modelos de IA: MiMo-V2.5-Pro, DeepSeek V4 Pro, DeepSeek V4 Flash y Qwen 3.7 Plus.

Tabla de contenido

Características

  • 300+ herramientas para flujos de trabajo completos de desarrollo en Godot
  • Manipulación de escenas en tiempo real — agrega, elimina, mueve, renombra y reconfigura nodos sin salir de tu chat de IA
  • Inspección de juego en tiempo de ejecución — consulta el árbol de escena en vivo, lee/escribe propiedades durante el juego, ejecuta GDScript en el juego en ejecución
  • Grabación y reproducción de entrada — graba sesiones de jugador, reproduce a velocidad variable, simula entrada de teclado/ratón/acción
  • Pruebas visuales con capturas de pantalla — captura capturas de pantalla del editor y del viewport del juego para verificaciones de regresión visual
  • Creación de animaciones — crea clips, agrega pistas, establece keyframes, construye máquinas de estado y árboles de mezcla
  • Configuración de física — agrega cuerpos, formas de colisión, raycasts, materiales de física; configura capas/máscaras
  • Gestión de audio — agrega reproductores, configura diseños de bus, inserta efectos (reverb, delay, chorus, etc.)
  • Navegación — configura regiones, agentes, hornea navmeshes, consulta pathfinding entre puntos
  • Edición de TileMap — establece celdas, rellena rectángulos, limpia áreas, lee datos de tiles
  • Herramientas de temas y shaders — crea temas, establece colores/fuentes/styleboxes; crea, edita y valida shaders
  • Operaciones por lotes — encuentra nodos por tipo, establece propiedades entre escenas, detecta dependencias circulares
  • Marco de pruebas — ejecuta escenarios de prueba de múltiples pasos, verifica el estado de los nodos, comprueba el texto en pantalla, ejecuta pruebas de estrés
  • Soporte de deshacer/rehacer — todas las mutaciones del editor pasan por el sistema de deshacer integrado de Godot
  • Escaneo automático de puertos — el servidor y el complemento negocian automáticamente en los puertos 6505-6514
  • Cero modificación del proyecto — se instala como un complemento estándar de Godot, no se requieren cambios en el motor

Arquitectura

MCP Client (Claude, Cursor, VS Code, OpenCode)
    │  stdio (JSON-RPC 2.0)
    ▼
Node.js MCP Server (TypeScript)
    │  WebSocket (JSON-RPC 2.0)
    ▼
Godot Editor Plugin (GDScript)
    ├── Command Router → 40+ command modules → 300+ tools
    ├── UndoRedo Helper
    └── Runtime Autoload (mcp_runtime.gd)
        — scene tree queries, property R/W, input simulation,
          screenshot capture, signal watching

Flujo de datos: el cliente de IA envía una llamada de herramienta a través de stdio → el servidor MCP busca la herramienta en el registro → la reenvía a través de WebSocket al complemento de Godot → el enrutador de comandos la despacha al módulo correcto → el módulo llama a la API del editor de Godot (con deshacer/rehacer) → el resultado regresa al cliente de IA.

Consulta el sitio web para ver un diagrama de arquitectura detallado.

Instalación

Requisitos previos

  • Godot 4.x (probado con 4.7)
  • Un cliente de IA compatible con MCP (Claude Desktop, Cursor, VS Code con Copilot, OpenCode, etc.)

Complemento de Godot

Opción A — Descargar desde Lanzamientos (recomendado)

  1. Ve a la página de Lanzamientos y descarga el último archivo zip addons (por ejemplo, keeveeg-godot-mcp-v1.1.0-addons.zip).
  2. Extrae el zip en la raíz de tu proyecto de Godot — esto coloca addons/godot_mcp/ en la ubicación correcta.
  3. Abre tu proyecto en Godot.
  4. Ve a Proyecto → Configuración del proyecto → Plugins.
  5. Encuentra Godot MCP en la lista y ponlo en Activo.

Opción B — Copiar desde el repositorio

  1. Copia la carpeta addons/godot_mcp/ de este repositorio en el directorio addons/ de tu proyecto.
  2. Abre tu proyecto en Godot.
  3. Ve a Proyecto → Configuración del proyecto → Plugins.
  4. Encuentra Godot MCP en la lista y ponlo en Activo.

Después de habilitarlo, el complemento escanea los puertos 6505-6514 en busca de un servidor MCP en ejecución. Una vez conectado, la pestaña MCP aparece en el panel inferior mostrando el estado de conexión y el registro de actividad.

Configuración

Cliente MCP

Añade lo siguiente al archivo de configuración de tu cliente MCP:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@keeveeg/godot-mcp"]
    }
  }
}

Para desarrollo local, usa la ruta completa:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/server/dist/index.js"]
    }
  }
}
ClienteArchivo de configuración
Claude Desktop~/.config/claude/claude_desktop_config.json (Linux/macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor.cursor/mcp.json en la raíz del proyecto
OpenCodeopencode.json en la raíz del proyecto o ~/.config/opencode/opencode.json globalmente

Ejemplo opencode.json:

{
  "mcp": {
    "godot": {
      "type": "local",
      "command": ["npx", "-y", "@keeveeg/godot-mcp"]
    }
  }
}

Variables de entorno

VariablePredeterminadoDescripción
GODOT_MCP_DEBUG(sin establecer)Establece cualquier valor para habilitar el registro de depuración en el servidor

Habilitar/Deshabilitar herramientas

Crea un archivo godot_mcp_config.json en la raíz de tu proyecto de Godot para deshabilitar herramientas de forma selectiva:

{
  "enabled_tools": {
    "delete_scene": false,
    "reload_project": false,
    "execute_editor_script": false
  }
}

Las herramientas no listadas en la configuración están habilitadas por defecto. El complemento lee este archivo al iniciar.

Herramientas

Todas las 300+ herramientas en más de 40 módulos están documentadas en el Catálogo de herramientas con descripciones buscables y agrupaciones por categoría.

Solución de problemas

Problemas de conexión

"El editor de Godot no está conectado"

El servidor MCP está en ejecución pero Godot aún no se ha conectado.

  • Asegúrate de que el editor de Godot esté abierto con el complemento MCP activo
  • Revisa el panel MCP en el dock inferior de Godot para ver el estado de conexión
  • Verifica que ningún firewall esté bloqueando conexiones localhost en los puertos 6505-6514
  • Revisa el registro de salida de Godot para ver mensajes [MCP]

"No se pudo vincular a ningún puerto en el rango 6505-6514"

Todos los puertos en el rango de escaneo están ocupados.

  • Comprueba si ya hay otra instancia del servidor MCP en ejecución
  • Termina cualquier proceso obsoleto node: pkill -f "godot-mcp" (Linux/macOS) o usa el Administrador de tareas (Windows)
  • El servidor intentará automáticamente el siguiente puerto disponible

Ruta de Godot no encontrada

  • Usa rutas con prefijo res:// (por ejemplo, res://scenes/main.tscn)
  • Usa get_filesystem_tree para verificar la estructura del proyecto
  • Asegúrate de que el proyecto de Godot sea el que crees que es (revisa get_project_info)

Tiempo de espera de WebSocket

"La solicitud expiró después de 30000ms"

  • El editor puede estar ocupado (compilando, cargando una escena grande)
  • Comprueba si un diálogo está bloqueando el editor (el complemento cierra automáticamente la mayoría de los diálogos durante el juego)
  • Intenta la solicitud de nuevo — para operaciones grandes, el editor puede necesitar más tiempo

El complemento no se carga

  • Verifica que el directorio addons/godot_mcp/ esté en la ubicación correcta
  • Ve a Proyecto → Configuración del proyecto → Plugins y comprueba si aparece Godot MCP
  • Si aparece pero está deshabilitado, actívalo
  • Revisa si hay errores de GDScript en el registro de salida
  • Intenta Proyecto → Recargar proyecto actual

Las herramientas de ejecución no funcionan

El autoload mcp_runtime.gd debe estar presente para que las herramientas de ejecución funcionen. El complemento lo registra automáticamente, pero verifica:

  1. Abre project.godot y revisa la sección [autoload]
  2. Deberías ver: mcp_runtime="res://addons/godot_mcp/services/mcp_runtime.gd"
  3. Importante: NO uses el prefijo * — el * significa "solo editor" y el autoload no se cargará en el juego
  4. Revisa el registro de salida de Godot para ver [MCP Runtime] Loaded and ready for IPC