godot-mcp

Un servidor MCP que permite a un agente de IA trabajar en un proyecto de Godot 4.x de la misma manera que lo haría un desarrollador: leer y editar escenas, escribir scripts, compilar, probar, ejecutar, mirar el resultado y depurar lo que ha ido mal.

Dos cosas lo diferencian de intentar adivinar formatos de archivo o lanzar procesos a ciegas:

• Le pregunta a Godot mismo. Los archivos de escena y recursos se analizan y se vuelven a serializar estructuralmente (comprobado byte-idénticos en una ida y vuelta contra un corpus real de proyectos), pero cualquier cosa que dependa del comportamiento del propio motor — introspección de C#, compilación de shaders, enlaces de entrada, estado del editor — se responde ejecutando Godot en modo headless o consultando a un editor activo, no reimplementando desde memoria la semántica de Godot.

• Falla de forma ruidosa. Cada modo de fallo medible en este proyecto — una pantalla no disponible, un ensamblado de C# sin compilar, un editor cerrado, un binario que no es de .NET — es un error nombrado, distintivo y con solución, no un resultado vacío silencioso. Consulta docs/capability-matrix.md para las mediciones en las que se basa esto; varias de ellas existen precisamente porque la señal obvia (código de salida, un valor devuelto no nulo) resultó ser una mentira.

50 herramientas, organizadas en cuatro niveles según lo que necesitan para funcionar. Consulta docs/tools.md para la referencia completa y docs/troubleshooting.md para saber qué hacer cuando una herramienta se niega a funcionar.

Requisitos

• Node.js >= 20

• Un binario de Godot 4.7+ (la matriz de capacidades se midió contra 4.7; se espera que las demás versiones 4.x se comporten de manera similar, pero no están verificadas)

• Para cualquier herramienta de C# (build_csharp, run_tests, csharp_script_info, validate_node_property y rutas de scripts C# a través de validate_script): una compilación de Godot con .NET/mono — la distribución normal, solo GDScript, no puede cargar ni inspeccionar .cs, y cada herramienta de C# detecta esto de antemano y se niega con NOT_MONO_BINARY en lugar de fallar a mitad de camino. La salida de --version de una compilación mono contiene .mono. y también incluye un directorio GodotSharp/ como vecino.

• Para las herramientas C# concretamente, un SDK de dotnet en PATH (build_csharp y run_tests lo invocan directamente; csharp_script_info y validate_node_property necesitan una compilación Debug preexistente, que se obtiene de build_csharp o de build_godot_artifacts).

Related MCP server: godot-mcp-pilot

Instalación y compilación

git clone <this-repo> godot-mcp
cd godot-mcp
npm install
npm run build

Esto produce dist/server.js, el punto de entrada que ejecuta un cliente MCP.

Configurar un cliente MCP

Apunta tu cliente a dist/server.js con node y dale una forma de encontrar un binario de Godot. La configuración más simple establece GODOT_PATH explícitamente:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64"
      }
    }
  }
}

Cómo encontra el servidor un binario de Godot

En orden, gana el primero que se encuentre:

1. Un argumento explícito binary pasado a la llamada de una herramienta.

2. La variable de entorno GODOT_PATH.

3. Un binario archivado en el directorio vendor/ del propio proyecto (buscando hasta 3 niveles de profundidad, prefiriendo uno cuyo nombre de archivo contenga żmono) — para proyectos que incluyen su propia compilación de Godot.

4. godot, godot4 o godot-mono en PATH.

Cómo encuentra el server un proyecto

En orden:

1. Un argumento explícito project pasado en una llamada de herramienta.

2. La variable de entorno GODOT_PROJECT.

3. Ascender desde el directorio de trabajo del proceso del servidor buscando project.godot.

If none of these resolves to a directory containing project.godot, tools requiring a project fail with PROJECT_NOT_FOUND.

GODOT_MCP_DOCS_CACHE

godot_class_doc y search_classes presentan un índice de referencias de clase preguntando al propio binario de Godot, que es suficientemente lento como para merecer en caché. El índice se escribe en $TMPDIR/godot-mcp-docs-cache/<godot-version>/ por defecto; define GODOT_MCP_DOCS_CACHE para guardarlo en algún lugar persistente. La caché se guarda por la versión de Godot, así que actualizar tu versión crea un índice nuevo en lugar de servir una versión caducante. Si tu cliente MCP ejecuta el servidor con un directorio de trabajo fuera del proyecto objetivo, establece GODOT_PROJECT explícitamente:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/dist/server.js"],
      "env": {
        "GODOT_PATH": "/path/to/Godot_v4.7-stable_mono_linux.x86_64",
        "GODOT_PROJECT": "/path/to/your/godot-project"
      }
    }
  }
}

Llama primero a godot_status en cualquier nueva sesión — informa de la ruta resuelta del binario, la versión, si es una compilación mono, la disponibilidad de pantalla, la raíz del proyecto y si el ensamblado de C# está compilado; así un agente (o tú) puede ver lo que es realmente posible antes de intentar nada.

Los cuatro niveles

Cada herramienta se sirve desde el nivel más bajo que puede responderla. Si una herramienta falla con TIER_UNAVAILABLE o DISPLAY_REQUIRED, esta es la razón:

El Nivel D no es un transporte distinto — es un límite de capacidad sobre el Nivel B. Solo capture_screenshot es de Nivel D: no existe una vía de renderizado headless en Godot, por lo que las capturas requieren una pantalla real, virtual o física. run_project con windowed: true tiene el mismo requisito.

Las herramientas del Nivel A (la mayoría de la edición de escenas, ajustes de proyecto, scripts y configuration) trabajan sin tener Godot instalado en absoluto: son operaciones de archivo puras, probadas contra un corpus de archivos .tscn/.tres/project.godot reales re-serializados byte-idénticamente. El Nivel B necesita un binario de Godot y/o dotnet en PATH o resuelto como arriba. El Nivel C necesita el addon del editor (próxima sección) — hasta que esté instalado y ejecutándose un editor con él habilitado, las cinco herramientas de puente del editor fallan con TIER_UNAVAILABLE, lo cual se espera, no es un error; el mensaje de error te dice cuál de dos situaciones distintas se aplica (consulta docs/troubleshooting.md).

Consulta docs/tools.md para conocer el nivel de cada herramienta.

Instalación del addon del editor (Nivel C)

Cinco herramientas — editor_state, get_selected_node, live_scene_tree, open_scene_in_editor y execute_editor_script — se comunican con un editor Godot activo y en ejecución mediante un socket TCP en loopback, en lugar de en el río un proceso. Esto requiere un pequeño addon de editor en addons GDScript, instalado y habilitado en el proyecto objetivo. No hay herramienta de instalación: escribir en el directorio addons/ de otro usuario y modificar su project.godot es exactamente lo que este proyecto evita hacer automáticamente por su disciplina de jaula de rutas. Esto es un único paso manual:

1. Copia addon/godot_mcp/ de este repositorio al directorio addons/ del proyecto objetivo, para que quede en <project>/addons/godot_mcp/plugin.cfg.

2. Habilitó el plugin (o bien en el editor: Project Settings > Plugins > godot_mcp > Enable, o bien añadiéndolo directamente a project.godot:

   [editor_plugins]
   
   enabled=PackedStringArray("res://addons/godot_mcp/plugin.cfg")

3. (Si no estaba no abierto) (Re)abre el editor de Godot de ese proyecto — también funciona en modo headless (--headless --editor --path <project>), no se necesita pantalla. En su arranque, el addon escribe un archivo de inicio de retrocomunicación en <project>/.godot/mcp_bridge.json; las cinco herramientas lo leer para encontrar el puerto del puente y su token por sesión.

Ten en cuenta que el estado de selección del editor siempre está vacío en un editor headless — es normal (get_selected_node informa de "nothing selected" como resultado normal, no como error).

Cache

• Jaula de rutas. Cada ruta de escritura — escena, script, recurso, salida de captura de pantalla — se resuelve y se obliga a estar dentro de la raíz del proyecto. Una ruta que se salga de ella, directamente o a través de un symline, se rechaza con PATH_OUTSIDE_PROJECT antes de tocar nada.

• dy_run. Todas las herramientas que modifican aceptan dry_run y devuelven un diff unificado en lugar de escribir. Úsalo para previsualizar un cambio antes de confirmarlo.

• No hay almacén de copias de seguridad. El control de versiones es el sistema de deshacer. Es una simplificación deliberada: el servidor para que no existe ningún mecanismo de instantáneas ni de copia de seguridad. Si tu proyecto no está bajo control de versiones, usa dry_run antes de cualquier llamada mutadora, o ponlo bajo control de versiones.

• execute_editor_script no es una caja sin arena. Ejecuta una GDScript arbitraria dentro de tu tienen proceso del editor en ejecución, con los mismos privilegios que su editor: puede leer y modificar el estado vivo del editor, la escena abierta y cualquier otra cosa alcanzable desde GDScript. Trátalo como entregarás un intérprete de comandos a un agente: es adecuado para un agente de confianza que trabaja en tu propio proyecto, no para entradas no confiables.

Pruebas

npm test

Ejecuta tsc --noEmit contra tsconfig.json y tsconfig.test.json, y después la suite completa de Vitest. Casi cada test está al nivel de "parser": alimenta los parsers con salida de PHP / Godot/MSPBuild prefabricada y comprueba el resultado estructurado, de modo que la suite se ejecuta sin tener Godot instalado ni cadena .NET, y sigue siendo rápida y portable (CI, contenedores, un proceso sin nada de eso).

GODOT_TEST_BINARY

Dos bloques son diferentes: tests/integration/tier-b.test.ts maneja un binario de Godot real, construyendo proyectos temporales en disco e invocando validate_target, check_shaders, run_project, y godot_class_doc contra él — porque un driver se puede probar contra texto fijo infinidad, sin demostrar jamás que el código de la propia herramienta, para lanzar procesos, contruir argumentos y leer streams, funciona de verdad contra el motor real. tests/integration/tier-c.test.ts hace lo mismo con las herramientas del puente del editor, pero con un requisito materialmente distinto: debe lanzar un editor Godot real como un proceso shield de larga duración (el editor no se cierra solo) y reclamarlo después de forma segura, incluso si falla la prueba.

• No establecido (por defecto): ambos bloques se reportan como SKIPPED. Nada más en npm test se ve.

• Establecido a la ruta de un binario de Godot 4.7+: ambos bloques se ejecutan de verdad real contra él.

GODOT_TEST_BINARY=/path/to/Godot_v4.7-stable_linux.x86_64 npm test

No es necesaria una compilación mono/.NET para este bloque. Si también estás trabajando en las herramientas focalizadas en C# (build_csharp, run_tests), aparte tendrás que tener un dotnet en PATH; no hay por ahora una variable de compuerta equivalente para eso, porque ninguna de las pruebas del bloque GODOT_TEST_BINARY la necesita.

Documentación

• docs/tools.md — todas las herramientas, agrupadas por área, con el nivel y las entradas clave.

• docs/troubleshooting.md — modos de fallo medidos y sus soluciones.

• docs/capability-matrix.md — las mediciones empíricas en las que se basa el comportamiento de este proyecto.