godot-mcp-runtime

MCP de Playwright para Godot, capturas de pantalla, manipulación de SceneTree y ejecución arbitraria de GDScript en tiempo de ejecución a través de un puente UDP local.

GitHub

Prueba este MCPPatrocinado

Documentación

Godot MCP Runtime

Un servidor MCP ligero que combina edición headless completa con control total del runtime sobre un proyecto de Godot 4.x. Las operaciones de escenas, nodos, autoloads y validación cubren todo excepto los rincones más nicho del motor; el puente de runtime añade capturas de pantalla, simulación de entrada, descubrimiento de UI y GDScript en vivo contra el árbol de escenas en ejecución.

Agent driving a Godot game via MCP runtime tools

La IA no solo escribe tu juego, puede verificar su trabajo.

Edición headless: escenas, nodos, scripts, señales, validación, sin ventana de editor
Control de runtime: capturas de pantalla, simulación de entrada, descubrimiento de UI, GDScript en vivo y perfilado de funciones contra el juego en ejecución
Huella cero: sin addon de Godot, sin commits al proyecto, limpieza automática al apagar

No se requiere addon. La mayoría de los servidores MCP de Godot que ofrecen soporte de runtime se distribuyen como un addon de Godot, algo que instalas en tu proyecto, commiteas al control de versiones y gestionas como dependencia. Usa npx y no hay instalación ni configuración necesaria.

Piénsalo como Playwright MCP, pero para Godot. Esto hace lo mismo para juegos: ejecuta el proyecto, toma una captura de pantalla, simula entrada, lee lo que hay en pantalla, ejecuta un script contra el árbol de escenas en vivo. El agente cierra el ciclo sobre sus propios cambios en lugar de delegarte la verificación.

[!NOTE] Esto no reemplaza el playtesting. No detecta los problemas sutiles de sensación que solo un humano nota, y no te dirá si tu juego es divertido. Lo que hace es permitir que un agente confirme que una escena carga, que un botón responde, que un valor se actualizó, que un script se ejecutó sin errores. La capacidad de verificar el trabajo es crucial para flujos de trabajo impulsados por IA.

Qué Hace

Construido para agentes. Cada herramienta está diseñada con un propósito y se autodocumenta. Cuando algo falla, la respuesta le dice al agente cómo arreglarlo; cuando algo tiene éxito, apunta hacia el siguiente paso. El resultado es una IA que no se atasca y se autocorrige sin necesidad de que la empujes.

Edición headless. Crea escenas, añade nodos, establece propiedades, adjunta scripts, conecta señales, valida GDScript. Todas las operaciones estándar, sin necesidad de ventana de editor.

Puente de runtime. Cuando se llama a run_project o attach_project, el servidor inyecta McpBridge como autoload. Esto abre un listener TCP solo-localhost (ambos auto-seleccionan un puerto libre cuando se omite bridgePort; pasa bridgePort para fijar un puerto específico) y habilita:

Capturas de pantalla: Captura el viewport. Por defecto devuelve una vista previa de 960x540 en línea más el PNG completo en disco; usa responseMode: 'full' para pixel-perfect o 'path_only' para omitir la imagen en línea
Simulación de entrada: Secuencias por lotes de pulsaciones de teclas, clics de ratón, movimiento de ratón, clics en elementos de UI por nombre o ruta, eventos de acción de Godot, texto escrito en el Control enfocado y esperas temporizadas. Cada acción informa lo que hizo: el Control que golpeó, las señales que disparó y qué cambió en pantalla
Descubrimiento de UI: Recorre el árbol de escenas en vivo y recoge cada nodo Control visible con su posición, tipo, contenido de texto y estado deshabilitado
Ejecución de scripts en vivo: Compila y ejecuta GDScript arbitrario con acceso completo al SceneTree mientras el juego está en ejecución
Perfilado de funciones: Con profiling: true al inicio, captura el propio profiler de Godot y clasifica las funciones GDScript más costosas por tiempo propio o inclusivo, con ubicaciones de origen y promedios por fotograma

Modo fondo. Pasa background: true a run_project y la ventana de Godot se mueve fuera de pantalla (posicionada en (-9999, -9999)) con entrada física bloqueada: sin bordes, no enfocable, con paso de ratón. La entrada programática, las capturas de pantalla y todas las herramientas de runtime funcionan exactamente igual. Útil para pruebas automatizadas impulsadas por agentes donde la ventana no debería ser visible ni interactiva.

Modo de adjunto manual. Cuando algo distinto de MCP lanza el juego (un pipeline de CI, un depurador externo, tu propio shell), llama a attach_project primero. Inyecta el puente y marca el proyecto como activo sin lanzar Godot, así cuando lances el juego manualmente, las herramientas de runtime funcionarán contra él. Usa detach_project cuando termines.

[!IMPORTANT] get_debug_output no está disponible en modo adjunto. stdout y stderr solo fluyen a través de procesos que MCP inició él mismo, así que cuando Godot se lanza externamente no hay salida capturada que devolver. Usa run_project si necesitas el flujo de depuración.

El puente se limpia automáticamente - en stop_project o detach_project, y también sin llamada de herramienta cuando el juego sale por sí solo, la conexión del puente se cae, o el servidor se apaga (incluyendo un cliente que simplemente cierra la conexión). Sus artefactos viven bajo .mcp/godot-runtime/ en el proyecto, que el servidor añade a .gitignore. Sin autoloads sobrantes, sin archivos de proyecto modificados.

Cómo Se Compara

El espacio MCP de Godot se divide en dos ejes: si un servidor puede conducir un juego en ejecución (runtime) o solo editar archivos, y qué le cuesta a tu proyecto hacerlo. La mayoría de los servidores que ofrecen control de runtime real se distribuyen como un addon de Godot que instalas y commiteas al control de versiones, o como un motor personalizado que descargas. Este inyecta un puente transitoriamente y lo elimina al apagar, así obtienes control completo del juego en vivo contra Godot estándar sin dejar nada en tu repositorio.

Servidor	Runtime de juego en vivo	Huella	Licencia	Precio
Godot MCP Runtime	Completo: capturas, entrada, árbol de escenas en vivo, ejecución de scripts	Cero (`npx`, sin addon commiteado)	MIT	Gratis
Summer Engine	Completo	Descarga de motor personalizado + inicio de sesión	Capa MIT / motor propietario	Núcleo gratis, nube de pago
tugcantopaloglu/godot-mcp	Completo	Addon autoload commiteado	MIT	Gratis
Godot MCP Pro	Completo	Addon de editor commiteado	Propietario	$15
GDAI MCP	Mediado por editor	Addon de editor commiteado	Propietario	$19
Coding-Solo/godot-mcp	No (lanzamiento + salida de depuración)	Cero (`npx`)	MIT	Gratis

Entre los servidores con control completo de juego en vivo, Godot MCP Runtime combina una instalación de huella cero (sin addon commiteado al control de versiones, sin motor personalizado, sin cuenta) con un solo comando npx, y ha distribuido este puente de runtime autoload transitorio desde febrero de 2026. Otro proyecto, Vollkorn-Games/godot-mcp, llegó independientemente al mismo diseño al mismo tiempo y es el único otro servidor en este nicho; está en una etapa más temprana y se instala desde el código fuente en lugar de npm. Para el campo completo de ~20 servidores con una fuente para cada afirmación, ver docs/comparison.md.

Inicio Rápido

Requisitos Previos

Node.js v20+
Godot 4.x

Eso es todo. Sin addon de Godot, sin modificaciones al proyecto.

Configura Tu Cliente MCP

Añade lo siguiente a la configuración de tu cliente MCP. Funciona con Claude Code, Claude Desktop, Cursor o cualquier cliente compatible con MCP.

Instalación cero mediante npx (recomendado):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

O instala globalmente:

npm install -g godot-mcp-runtime

{
  "mcpServers": {
    "godot": {
      "command": "godot-mcp-runtime",
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

O clona desde el código fuente:

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

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["<path-to>/godot-mcp-runtime/dist/index.js"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>"
      }
    }
  }
}

[!TIP] ¿Prefieres pnpm? Las tres rutas de instalación funcionan con pnpm. Sustituye pnpm dlx godot-mcp-runtime por npx -y godot-mcp-runtime, pnpm add -g godot-mcp-runtime para la instalación global, o pnpm install && pnpm run build para la compilación desde el código fuente. pnpm incluye valores predeterminados más sólidos contra ataques a la cadena de suministro de npm; ver la guía de seguridad de la cadena de suministro de pnpm.

O instala una rama/commit específico (por ejemplo, para probar una corrección no publicada o una rama de PR):

npx -y github:Erodenn/godot-mcp-runtime#<branch-or-commit>

[!WARNING] Instalar desde una referencia git (no del registro npm) descarga devDependencies y ejecuta tsc en tu máquina como parte de la instalación. Si no quieres un paso de compilación local, usa la instalación del registro (npx -y godot-mcp-runtime) en su lugar.

Si Godot está en tu PATH, puedes omitir GODOT_PATH por completo. El servidor lo detectará automáticamente.

Variables de entorno opcionales

Todas se establecen en el mismo bloque env que GODOT_PATH:

Variable	Efecto
`DEBUG`	`"true"` habilita el registro verbose de `[DEBUG]`.

Los tres indicadores de puerta de seguridad a continuación comparten un eje (ver docs/security.md para el panorama completo) y son demasiado anchos para envolverse bien en una tabla, así que reciben una lista en su lugar:

GODOT_MCP_DISABLE_ELICITATION - "true" deshabilita los avisos de confirmación para run_project y run_script. Úsalo si tu cliente no puede mostrar avisos de elicitación (por ejemplo, Claude Desktop, que los cancela automáticamente). Fail-open: la acción procede con una advertencia. Los bloqueos duros de seguridad de Nivel 1 siguen aplicándose.
GODOT_MCP_STRICT - "true" rechaza duramente cualquier cosa que de otro modo avisaría, para operación desatendida. Tiene prioridad sobre GODOT_MCP_DISABLE_ELICITATION cuando ambos están establecidos.
GODOT_MCP_DISABLE_SECURITY - "true" desactiva toda la puerta de seguridad run_script/run_project: sin escaneo, sin bloqueo, sin elicitación, sin advertencias, sin sidecars de auditoría - Nivel 1 incluido. Anula GODOT_MCP_STRICT cuando ambos están establecidos. Habilitar esto es una decisión humana - un agente debería negarse a establecerlo en nombre de un usuario.

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "godot-mcp-runtime"],
      "env": {
        "GODOT_PATH": "<path-to-godot-executable>",
        "GODOT_MCP_DISABLE_ELICITATION": "true"
      }
    }
  }
}

[!IMPORTANT] Errores comunes de rutas en Windows. GODOT_PATH debe apuntar al ejecutable de Godot en sí, no a su carpeta de instalación. Las barras invertidas en JSON deben escaparse o reemplazarse con barras normales:
"GODOT_PATH": "D:\\Godot\\Godot_v4.4-stable_win64.exe"
// o equivalentemente
"GODOT_PATH": "D:/Godot/Godot_v4.4-stable_win64.exe"
Establecer la variable desde un .bat envoltorio no se propaga al servidor MCP - la ruta debe vivir en el bloque env del cliente anterior.

Verificar

Pide a tu asistente de IA que llame a check_project. Si devuelve una cadena de versión de Godot (por ejemplo, 4.4.stable), estás conectado y funcionando.

Documentación

docs/tools.md: referencia completa de herramientas, agrupadas por categoría
docs/tool-authoring.md: estándares para añadir o modificar herramientas
docs/architecture.md: estructura del código fuente, diagrama de secuencia del puente, pasos del ciclo de vida, comportamiento de los artefactos de runtime
docs/security.md: modelo de seguridad de run_script / run_project, catálogo completo de reglas, comportamiento en modo estricto

Agradecimientos

Construido sobre la base establecida por Coding-Solo/godot-mcp para operaciones headless de Godot.

Desarrollado con Claude Code.

Licencia

MIT