Godot-MCP

Servidor MCP de código abierto que conecta agentes de IA al Editor y runtime de Godot (Godot 4.x, C#).

Documentación

✨ Desarrollador de Juegos con IA — Godot MCP

Godot MCP es un asistente de desarrollo de juegos impulsado por IA para el Editor de Godot. Conecta Claude, Cursor, Copilot o cualquier agente compatible con MCP a Godot y deja que inspeccione y controle tu proyecto: crea nodos, edita escenas, gestiona recursos y scripts, captura capturas de pantalla y más.

Godot-MCP es la contraparte de Godot de Unity-MCP: un addon de editor en C# que expone las operaciones del Editor de Godot como Herramientas de IA y las conecta a un servidor MCP a través del mismo backend en la nube alojado (ai-game.dev) que impulsa Unity-MCP — o tu propio servidor autoalojado. La pila de MCP / reflexión no está bifurcada: se comparte con Unity-MCP y se consume desde nuget.org como PackageReferences.

💬 Únete a nuestro servidor de Discord — ¡Haz preguntas, muestra tu trabajo y conéctate con otros desarrolladores!

✔️ Agentes de IA — Usa los mejores agentes de Anthropic, OpenAI, Google o cualquier otro proveedor sin bloqueo de proveedor
✔️ 42 herramientas integradas — Una amplia gama de Herramientas MCP en 12 familias para operar el Editor de Godot
✔️ C# y GDScript — Lee, crea y actualiza scripts tanto .cs como .gd, y adjúntalos a nodos
✔️ Control de escenas y nodos — Construye y edita el árbol de escenas, abre/guarda escenas .tscn, muta recursos .tres/.res
✔️ Retroalimentación visual — Captura capturas de pantalla del viewport, la cámara y nodos aislados que el LLM puede inspeccionar
✔️ Vía de escape de reflexión — Encuentra y llama cualquier método C# en los ensamblados cargados a través de ReflectorNet
✔️ Nube o autoalojado — Conéctate a ai-game.dev de inmediato, o apunta a tu propio servidor
✔️ Conversación natural — Chatea con la IA como lo harías con un humano

AI Game Developer — Godot MCP

Inicio Rápido

Ponte en marcha desde una terminal usando el godot-cli (el análogo de Godot de unity-mcp-cli) — sin necesidad de copiar archivos manualmente ni editar el csproj:

# 1. Install godot-cli
npm install -g godot-cli

# 2. (Optional) Scaffold a fresh Godot C# project — skip if you already have one
godot-cli create-project --dotnet ./MyGodotProject

# 3. Install the godot_mcp addon: downloads addons/godot_mcp/ from the matching
#    GitHub release, adds the required NuGet packages + the extension-catalog
#    EmbeddedResource to your .csproj, and enables the plugin in project.godot —
#    all idempotently
godot-cli install-plugin ./MyGodotProject

# 4. Sign in to the ai-game.dev cloud — OAuth 2.1 device login (opens a browser,
#    saves a machine-wide credential the editor plugin auto-adopts; no token to copy)
godot-cli login

# 5. Pick an AI agent (Claude Code, Cursor, Copilot, …) and write its MCP config —
#    pinned to THIS project's cloud route by default (pass --no-pin for the bare URL)
godot-cli setup-mcp claude-code ./MyGodotProject

# 6. Open the Godot editor — builds the C# assembly first (so the addon loads on
#    the very first open) then auto-connects with the right GODOT_MCP_* env vars
godot-cli open ./MyGodotProject

# 7. Wait until the plugin answers the readiness probe
godot-cli wait-for-ready ./MyGodotProject

Eso es todo. Pídele a tu IA "Crea 3 cubos en un círculo con radio 2" y míralo suceder. ✨

Instalación sin conexión / desarrollo: install-plugin --source <path-to>/addons/godot_mcp copia el addon desde un directorio local en lugar de descargarlo. Prefiere la versión de lanzamiento correspondiente con install-plugin --version <x.y.z> si necesitas una compilación específica del addon. La ruta manual (copiar el addon + agregar los paquetes NuGet tú mismo) todavía está documentada en Instalación Pasos 1–2 para los flujos de la Biblioteca de Activos / gestión manual.

Consulta la documentación completa de la CLI para cada comando, el orden de resolución del editor y las variables de entorno de conexión.

Contenido

Inicio Rápido
Referencia de Herramientas
Requisitos
Instalación
Conectar
- Modo nube (predeterminado) — ai-game.dev
- Modo personalizado — tu propio servidor
Configuración de MCP Server de Godot
- Servidor local — deja que el addon lo descargue y ejecute por ti
- Compila y ejecuta el servidor manualmente (avanzado)
Personalizar Herramientas
Uso en tiempo de ejecución (en el juego)
Cómo funciona la Arquitectura de Godot MCP
Compilación y contribución
Licencia

AI Game Developer — Godot MCP

Referencia de Herramientas

Godot-MCP incluye 42 herramientas integradas agrupadas en 12 familias. Los nombres de las herramientas reflejan Unity-MCP cuando tiene sentido (scene-*, node-*, …). Cada herramienta devuelve un resultado estructurado, serializado con ReflectorNet (o una imagen PNG para capturas de pantalla). Todas las herramientas del editor están disponibles inmediatamente después de que el addon esté habilitado — no se requiere configuración adicional. La familia runtime-errors es la excepción: muestra errores del juego en ejecución y está DESACTIVADA por defecto — actívala con builder.WithRuntimeErrorCapture() (consulta Capturando errores de tiempo de ejecución en el juego).

Familia	Herramientas	Qué hace
ping	`ping`	Sonda de preparación ligera — devuelve un mensaje, o retorna `pong`. Verifica la ruta MCP de extremo a extremo (editor → SignalR → despacho de herramientas). Herramienta de sistema — accesible a través de la superficie HTTP `/api/system-tools/` del servidor, no anunciada a los agentes de IA en `tools/list`.
node	`node-find`, `node-create`, `node-modify`, `node-set-parent`, `node-reorder`, `node-duplicate`, `node-delete`	Inspecciona y edita el árbol de escenas activo (el análogo de Godot de los GameObjects de Unity), manejando `EditorInterface` en el hilo principal. El orden de los hijos — que es el orden de diseño en un `VBoxContainer`/`HBoxContainer` — se puede establecer tanto en la creación (`node-create`'s `index`) como después (`node-reorder`).
scene	`scene-open`, `scene-save`, `scene-create`, `scene-list-opened`, `scene-get-data`	Abre, guarda, crea e inspecciona escenas de Godot (`res://*.tscn` PackedScenes) en el editor.
resource	`resource-find`, `resource-get-data`, `resource-modify`, `resource-create`, `resource-move`, `resource-delete`	Encuentra y muta recursos de Godot (`.tres`/`.res`) a través de `ResourceLoader`/`ResourceSaver`/`EditorFileSystem`, manteniendo consistentes los sidecars `.import`.
filesystem	`filesystem-list`, `filesystem-reimport`	Navega y reimporta el árbol `res://` del proyecto a través del índice `EditorFileSystem` del editor (tipos de archivo + uids sin cargar recursos).
script	`script-read`, `script-create`, `script-update`, `script-delete`, `script-attach-to-node`, `script-validate`	CRUD en archivos C# (`.cs`) y GDScript (`.gd`), además de adjuntar un script a un nodo y validar GDScript.
screenshot	`screenshot-viewport`, `screenshot-camera`, `screenshot-isolated`	Captura el viewport del editor, una cámara específica o un render de nodo aislado, devuelto como una imagen PNG que el LLM puede inspeccionar.
editor	`editor-application-get-state`, `editor-application-set-state`, `editor-selection-get`, `editor-selection-set`	Lee/controla el ciclo de ejecución y reproducción del editor (Godot lanza el juego en un proceso separado) y la selección actual.
console	`console-get-logs`, `console-clear-logs`	Lee y limpia el recolector de registros del editor del plugin (`GD.Print`/`GD.PushWarning`/`GD.PushError`).
reflection	`reflection-method-find`, `reflection-method-call`	Encuentra y llama métodos C# (estáticos/instancia, públicos/privados) en todos los ensamblados cargados a través de ReflectorNet — la vía de escape independiente del motor.
skills	`godot-skill-create`, `godot-skill-generate`	Crea una nueva herramienta MCP como archivo C# en el proyecto y regenera los archivos `SKILL.md` a partir de las herramientas que el editor tiene registradas actualmente. Herramientas de sistema — accesibles a través de la superficie HTTP `/api/system-tools/` del servidor (como `ping`), no anunciadas a los agentes de IA en `tools/list`.
runtime-errors	`runtime-errors-get`, `runtime-errors-clear`	Consulta errores generados dentro del juego en ejecución (NO el editor) — errores de tiempo de ejecución de GDScript, `push_error`/`push_warning`, errores de shader y excepciones C# no controladas / no observadas de `Task`, con backtraces GDScript de múltiples marcos en Godot 4.5+. DESACTIVADO por defecto — actívalo con `builder.WithRuntimeErrorCapture()`.

ping

ping — Sonda de preparación ligera; devuelve un mensaje, o retorna pong. Una herramienta de sistema: llámala a través de /api/system-tools/ping (o godot-cli run-system-tool ping); no está listada en tools/list.

node

node-find — Encuentra nodos en el árbol de escenas activo por ruta, tipo o nombre.
node-create — Crea un nuevo nodo bajo un padre (opcionalmente instanciando una sub-escena .tscn), opcionalmente en un index hermano específico (los conteos negativos van desde el final).
node-modify — Establece campos/propiedades en uno o más nodos.
node-set-parent — Reasigna nodos dentro del árbol de escenas.
node-reorder — Mueve un nodo existente a una posición diferente entre sus hermanos (Node.MoveChild) — la única forma de reorganizar una escena existente sin eliminar y recrear.
node-duplicate — Duplica nodos junto con sus subárboles.
node-delete — Elimina nodos de la escena activa.

scene

scene-open — Abre un res://*.tscn PackedScene en el editor.
scene-save — Guarda una escena abierta de vuelta a su archivo .tscn.
scene-create — Crea un nuevo activo de escena en el proyecto.
scene-list-opened — Lista las escenas actualmente abiertas en el editor.
scene-get-data — Recupera los nodos raíz / estructura de una escena.

resource

resource-find — Busca en el proyecto recursos (.tres/.res).
resource-get-data — Lee los campos y propiedades serializados de un recurso.
resource-modify — Modifica las propiedades de un recurso.
resource-create — Crea un nuevo activo de recurso.
resource-move — Mueve / renombra un recurso, manteniendo consistentes los sidecars .import.
resource-delete — Elimina un recurso del proyecto.

filesystem

filesystem-list — Navega el árbol res:// (tipos de archivo + uids) a través del índice de archivos del editor.
filesystem-reimport — Reimporta archivos en el proyecto.

script

script-read — Lee un archivo de script .cs / .gd.
script-create — Crea un nuevo archivo de script.
script-update — Actualiza el contenido de un archivo de script existente.
script-delete — Elimina un archivo de script.
script-attach-to-node — Adjunta un script a un nodo.
script-validate — Valida archivos GDScript (.gd) y devuelve diagnósticos estructurados de análisis/compilación.

screenshot

screenshot-viewport — Captura el viewport del editor como PNG.
screenshot-camera — Captura desde una cámara específica.
screenshot-isolated — Renderiza un nodo de forma aislada desde un ángulo elegido.

editor

editor-application-get-state — Lee el estado de ejecución/aplicación del editor.
editor-application-set-state — Inicia / detiene el juego en ejecución.
editor-selection-get — Obtiene la selección actual del editor.
editor-selection-set — Establece la selección actual del editor.

console

console-get-logs — Lee los registros del editor recopilados por el plugin (con filtrado). Esto incluye los diagnósticos del ciclo de vida de la conexión del plugin (conectar/desconectar, tiempo de espera de drenaje, guardar/cargar configuración, generación de habilidades, control de desarrollo, despachador y advertencias de captura en tiempo de ejecución), que se enrutan a través del mismo sumidero de captura que sus registros de framework.
console-clear-logs — Limpia la caché de registros recopilados.

reflection

reflection-method-find — Encuentra métodos de C# (incluidos los privados) en todos los ensamblados cargados.
reflection-method-call — Llama a cualquier método de C# con parámetros de entrada y obtiene el resultado.

runtime-errors (en el juego; DESACTIVADO por defecto — actívalo con builder.WithRuntimeErrorCapture())

runtime-errors-get — Lee los errores de tiempo de ejecución capturados en el juego (primero los más antiguos, página con los más recientes conservados); consulta solo errores nuevos mediante sinceSequence. Devuelve available:false cuando la captura nunca se habilitó, por lo que una lista vacía nunca se confunde con un estado saludable.
runtime-errors-clear — Limpia el búfer de errores de tiempo de ejecución capturados en el juego (sin operación cuando la captura no está habilitada); el contador de secuencia monótono se conserva.

skills (herramientas del sistema — servidas en /api/system-tools/, no anunciadas a los agentes de IA)

godot-skill-create — Escribe un nuevo archivo de herramienta MCP de C# (.cs) en el proyecto. La herramienta se vuelve invocable una vez que el proyecto se reconstruye (Godot compila C# fuera de banda).
godot-skill-generate — Regenera cada SKILL.md a partir de las herramientas actualmente registradas en el editor, en la carpeta de habilidades del agente de IA seleccionado.

AI Game Developer — Godot MCP

Requisitos

Godot 4.3+ — la edición C# / .NET (mono). El csproj del addon fija Godot.NET.Sdk/4.3.0 como su mínimo; las ediciones 4.x más nuevas (4.4, 4.5) funcionan.
.NET 8 SDK (net8.0).

[!IMPORTANT] Godot-MCP requiere la compilación mono (C#/.NET) de Godot — la compilación estándar (solo GDScript) no puede compilar el addon.

Instalación

Hay dos cosas que instalar: el addon (los archivos del plugin) y los dos paquetes NuGet de los que depende el C# del addon. Godot compila cada .cs bajo tu proyecto en un solo ensamblado, por lo que el .csproj de tu proyecto debe declarar las mismas referencias NuGet que el addon necesita — de lo contrario, el C# del addon no se compilará.

Paso 1: Agrega el addon

Elige una de las siguientes formas para obtener la carpeta addons/godot_mcp/ en tu proyecto C# de Godot.

Totalmente automatizado (recomendado para flujos de trabajo de terminal): godot-cli install-plugin ./MyGodotProject hace todo el Paso 1 y el Paso 2 en un solo comando — descarga addons/godot_mcp/ de la versión de GitHub correspondiente, agrega los dos paquetes NuGet y el <EmbeddedResource> del catálogo de extensiones a tu .csproj, y habilita el plugin en project.godot, de forma idempotente. Usa --source <path>/addons/godot_mcp para instalar desde una copia local sin conexión. Las Opciones manuales A–C a continuación permanecen para instalaciones en el editor (Biblioteca de Activos) y administradas manualmente.

Opción A — Biblioteca de Activos de Godot (recomendada)

El camino más fácil: instala directamente desde el editor.

Abre la pestaña AssetLib en la parte superior del editor de Godot.
Busca Godot-MCP y abre el activo.
Haz clic en Descargar, luego en Instalar — Godot descomprime el addon en el res://addons/godot_mcp/ de tu proyecto.

La entrada de la Biblioteca de Activos se publica por versión y siempre apunta a una versión etiquetada, por lo que una instalación en el editor te da una instantánea conocida y buena del addon. (Consulta la nota a continuación si la entrada aún no es visible).

Opción B — Zip de la versión de GitHub

Obtén el último godot-mcp-addon-<version>.zip de la página de Versiones y extráelo en la raíz de tu proyecto — el archivo ya contiene addons/godot_mcp/..., por lo que los archivos aterrizan en res://addons/godot_mcp/.

Opción C — Copiar desde el código fuente

Copia la carpeta addons/godot_mcp/ de este repositorio (o tu clon) en el directorio addons/ de tu proyecto manualmente.

Después de que los archivos estén en su lugar (Opciones A–C), habilita el plugin: Proyecto → Configuración del Proyecto → Plugins → Godot-MCP → Habilitar. (Si usaste el godot-cli install-plugin totalmente automatizado anterior, el plugin ya está habilitado y los paquetes NuGet + la incrustación del catálogo de extensiones ya están agregados — salta directamente al Paso 3). En una carga exitosa, el panel de Salida del editor imprime:

[Godot-MCP] plugin loaded

Disponibilidad de la Biblioteca de Activos. La entrada AssetLib en el editor (Opción A) aparece después de que la primera presentación del mantenedor sea aprobada por los moderadores de la Biblioteca de Activos de Godot. Hasta entonces, usa la Opción B (zip de la versión de GitHub) o la Opción C.

Paso 2: Agrega los paquetes NuGet + la incrustación del catálogo de extensiones

Agrega ambos PackageReferences y el <EmbeddedResource> del catálogo de extensiones al .csproj de tu proyecto (usa estas versiones fijadas exactas — deben coincidir con el Godot-MCP.csproj del addon):

<ItemGroup>
  <PackageReference Include="com.IvanMurzak.ReflectorNet" Version="5.4.1" />
  <PackageReference Include="com.IvanMurzak.McpPlugin"   Version="8.6.0" />
</ItemGroup>

<!-- Embed the extension catalog so the Extensions panel populates (else it is EMPTY). -->
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>

Paquete	Versión	Rol
`com.IvanMurzak.ReflectorNet`	`5.4.1`	Núcleo de reflexión / serialización
`com.IvanMurzak.McpPlugin`	`8.6.0`	Cliente del plugin MCP (trae transitivamente `McpPlugin.Common` + `ReflectorNet`; lleva el módulo compartido `AgentConfig`)

El <EmbeddedResource> es tan requerido como los pines NuGet: el registro de extensiones puramente administrado del addon lee el catálogo en tiempo de ejecución del editor mediante GetManifestResourceStream (sin res:// / respaldo del sistema de archivos), y debido a que el addon se envía como código fuente, su propio <EmbeddedResource> no se transfiere a tu proyecto — por lo que sin esta línea tu panel de Extensiones está vacío. El LogicalName debe ser exactamente Godot-MCP.extensions.catalog.json para que el recurso se resuelva de manera idéntica al ensamblado del propio addon.

Ejecuta dotnet restore para que los paquetes aterricen en tu caché de NuGet, luego compila. No se requiere copia manual de DLL — en tiempo de ejecución del editor, el resolvedor de ensamblados del addon localiza las DLL en tu carpeta global de paquetes de NuGet leyendo el *.deps.json de la compilación. (Si prefieres una salida autocontenida, establece <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> para que las DLL se copien junto a tu ensamblado del proyecto).

Paso 3: Instala un agente de IA

Elige un solo AI agent que prefieras — no necesitas instalar todos. Esta es tu ventana de chat principal para comunicarte con el LLM.

Claude Code (recomendado)
Claude Desktop
GitHub Copilot en VS Code
Antigravity
Cursor
Cualquier otro agente compatible con MCP

Escribe la configuración del cliente MCP del agente con godot-cli setup-mcp <agent> ./MyGodotProject. Por defecto, apunta el cliente a la URL de nube fijada al proyecto <host>/mcp/p/<pin>, por lo que una sesión de agente lanzada en esta carpeta de proyecto se enruta al editor de este proyecto incluso cuando tu cuenta tiene varios editores conectados; pasa --no-pin para la URL <host>/mcp simple. En modo Nube, la configuración lleva la clave de proyecto de este proyecto (Authorization: Bearer agd_pk_…) — una credencial que no expira, vinculada solo a este proyecto, creada con tu inicio de sesión de máquina; sin un inicio de sesión (o con --oauth) la configuración es solo URL y el agente inicia sesión con su propio OAuth. El botón Configurar del editor escribe la misma configuración. Consulta la documentación de CLI para la lista completa de agentes compatibles.

AI Game Developer — Godot MCP

Conectar

El plugin se conecta a un servidor MCP en uno de dos modos. El modo y su URL / token se pueden establecer en la configuración serializada o anularse al inicio del proceso con variables de entorno (útil para CI, ejecuciones sin cabeza y desarrollo local). Todos los nombres de variables son el análogo de Godot de UNITY_MCP_* de Unity-MCP. El modo activo siempre se recalcula desde el entorno, por lo que una anulación a nivel de proceso gana sobre la configuración serializada sin editar ningún archivo.

Modo Nube (predeterminado) — ai-game.dev

En el modo Nube, el plugin se conecta al backend alojado en https://ai-game.dev (la ruta del hub /mcp se agrega automáticamente). Este es el connectionMode predeterminado.

Inicia sesión una vez con godot-cli login. La autenticación en la nube usa el flujo de autorización de dispositivo OAuth 2.1 (RFC 8628): godot-cli login imprime un código de usuario corto, abre tu navegador y — tras la aprobación — guarda una credencial de nube en el almacén compartido de la máquina (~/.ai-game-dev/credentials.json) que el plugin del editor adopta automáticamente, por lo que godot-cli open se conecta sin token para copiar o pegar. No se genera ningún token de acceso personal (PAT). GODOT_MCP_TOKEN (a continuación) permanece disponible como anulación manual para CI / ejecuciones sin cabeza.

Variable de entorno	Propósito	Predeterminado
`GODOT_MCP_CONNECTION_MODE`	Fuerza el modo: `Cloud` o `Custom` (sin distinción de mayúsculas).	`Cloud`
`GODOT_MCP_CLOUD_URL`	Anula la URL base de la nube. Un `/mcp` final se elimina si está presente; un valor no http(s) vuelve al predeterminado.	`https://ai-game.dev`
`GODOT_MCP_TOKEN`	Token Bearer, enrutado al token del modo activo. Las comillas circundantes se recortan.	(ninguno)

Modo Personalizado — tu propio servidor

En el modo Personalizado, el plugin se conecta a una URL de servidor que tú proporcionas (un servidor de desarrollo local, una instancia autohospedada, etc.).

Variable de entorno	Propósito	Predeterminado
`GODOT_MCP_CONNECTION_MODE`	Establece en `Custom` para seleccionar este modo.	`Cloud`
`GODOT_MCP_HOST`	La URL del servidor personalizado. Debe ser una URL http(s) absoluta o vuelve al predeterminado.	`http://localhost:8080`
`GODOT_MCP_TOKEN`	Token Bearer (solo se necesita si el servidor requiere autorización).	(ninguno)

Ejemplo — inicia el editor apuntando a un servidor local:

export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:5300
# export GODOT_MCP_TOKEN=...   # only if the server enforces auth

El comando godot-cli open reenvía estas variables de entorno por ti mediante las banderas --mode, --url, --cloud-url y --token.

AI Game Developer — Godot MCP

Configuración de Godot `MCP Server`

En el modo Nube no ejecutas un servidor en absoluto — el plugin habla con ai-game.dev. Si quieres alojar el servidor tú mismo (desarrollo local, CI o tu propia nube), tienes dos opciones: deja que el addon descargue y ejecute el binario del servidor coincidente por ti (recomendado), o ejecútalo manualmente (avanzado).

El servidor en sí es el compartido, independiente del motor GameDev-MCP-Server — un binario de servidor (gamedev-mcp-server) que sirve a Unity-MCP, Godot-MCP y Unreal-MCP. Se publica desde su propio repositorio en su propia línea de versiones; este addon fija la versión del servidor que consume (la constante ServerVersion en addons/godot_mcp/Runtime/Connection/GodotMcpServerView.cs).

Servidor local — deja que el addon lo descargue y ejecute por ti

En el modo Personalizado, el plugin puede alojar su propio servidor MCP — no tienes que compilar o lanzar nada manualmente. Abre la tarjeta Servidor del dock del addon mientras el modo Personalizado está seleccionado y usa la fila Servidor local:

Iniciar servidor — descarga la compilación del servidor para la versión de servidor fijada, la almacena en caché, la lanza, y el complemento se conecta a ella. Detener servidor la termina (también se detiene automáticamente cuando cierras el editor).
La descarga es el recurso de lanzamiento específico de la plataforma gamedev-mcp-server-<rid>.zip — obtenido solo a través de HTTPS desde github.com, desde el lanzamiento de GameDev-MCP-Server etiquetado v<ServerVersion>, por lo que la URL del recurso es: https://github.com/IvanMurzak/GameDev-MCP-Server/releases/download/v<ServerVersion>/gamedev-mcp-server-<rid>.zip. El <rid> (identificador de tiempo de ejecución de la plataforma — p. ej. win-x64, osx-arm64, linux-x64) se resuelve automáticamente para tu máquina; los siete RID publicados son compatibles (win-x64/x86/arm64, linux-x64/arm64, osx-x64/arm64).
El binario se almacena en caché en la carpeta .godot/mcp-server/<rid>/ de tu proyecto (ignorada por git) y se reutiliza en lanzamientos posteriores; solo se vuelve a descargar cuando cambia la versión de servidor fijada (una coincidencia exacta de versión, por lo que el complemento del editor y el servidor con el que habla nunca se desincronizan). El servidor se lanza en el puerto de tu URL de servidor (por defecto http://localhost:8080), a través del transporte streamableHttp.

Fijación de versión y seguridad. La URL de descarga se deriva únicamente de la constante ServerVersion fijada del addon y de tu RID de plataforma — no hay ejecución de binarios con URL arbitraria. La versión del addon y la versión del servidor están desacopladas: aumentar la versión del servidor consumido es un cambio explícito del addon (un nuevo ServerVersion), y el lanzamiento v<ServerVersion> fijado debe existir ya en GameDev-MCP-Server antes de un lanzamiento del addon que lo fije. Si el recurso del lanzamiento no se puede obtener (estás sin conexión), el addon registra una advertencia y el servidor local simplemente no se inicia — recurre a la ejecución manual a continuación, o usa el modo Cloud. La descarga se omite por completo en CI (el entorno CI / GITHUB_ACTIONS), donde no se aloja ningún servidor local.

Esto refleja el flujo de servidor autohospedado de Unity-MCP: el complemento del editor gestiona el binario del servidor fijado por ti en lugar de requerir una compilación manual.

Ejecutar el servidor manualmente (avanzado)

Para ejecutar el servidor como un proceso independiente / en la nube, descarga un binario del lanzamiento de GameDev-MCP-Server (o usa la imagen Docker aigamedeveloper/mcp-server). Ambos transportes son compatibles: streamableHttp (HTTP) y stdio.

# HTTP transport on port 8080
./gamedev-mcp-server --client-transport streamableHttp --port 8080

# stdio transport — for local MCP clients that launch the server directly
./gamedev-mcp-server --client-transport stdio

Luego apunta el complemento hacia él en modo Personalizado (GODOT_MCP_HOST=http://localhost:8080).

Elegir un transporte: usa stdio cuando el cliente MCP lanza el binario del servidor directamente (uso local — la configuración más común); usa streamableHttp cuando ejecutas el servidor como un proceso independiente o en la nube y te conectas por HTTP.

Consulta el README de GameDev-MCP-Server para la tabla completa de argumentos / variables de entorno, la imagen Docker y la matriz de compilación multiplataforma.

AI Game Developer — Godot MCP

Personalizar herramientas

Godot-MCP admite el desarrollo de MCP Tool personalizados directamente en el código de tu proyecto. Una familia de herramientas es un partial class decorado con [AiToolType]; cada método de herramienta está decorado con [AiTool("tool-name", …)] con un [Description] en el método y en cada parámetro para ayudar al LLM a entenderlo.

Cualquier llamada a la API de Godot (Node, Resource, EditorInterface, …) debe ejecutarse en el hilo principal del editor — envíala a través de MainThread.Instance.Run(...) (el MainThread de ReflectorNet está respaldado por el despachador del hilo principal de Godot al iniciar el complemento). Nunca toques objetos del motor fuera del hilo.

[AiToolType]
public partial class Tool_MyFeature
{
    [AiTool("my-custom-task", Title = "Do a custom task")]
    [Description("Explain to the LLM what this does and when to call it.")]
    public string CustomTask
    (
        [Description("Explain to the LLM what this parameter is.")]
        string inputData
    )
    {
        // ... work that does not touch the Godot API can run on this background thread ...

        return MainThread.Instance.Run(() =>
        {
            // ... touch EditorInterface / Node / Resource here, on the main thread ...
            return "[Success] Operation completed.";
        });
    }
}

Devuelve un modelo de datos estructurado (serializado por ReflectorNet) o void para operaciones solo de efectos secundarios — nunca uses formato de cadena ad hoc para salida analizable. Usa parámetros string? optional = null (anulables + predeterminados) para marcarlos como opcionales para el LLM.

AI Game Developer — Godot MCP

Uso en tiempo de ejecución (en el juego)

Todo lo anterior ejecuta la conexión MCP dentro del editor de Godot (el [Tool] EditorPlugin lo inicia por ti). Godot-MCP también puede ejecutarse dentro de una compilación de juego en ejecución / exportada (depuración o lanzamiento) — el análogo en Godot del modo de tiempo de ejecución de Unity-MCP. Esto permite que un LLM lea y controle tu estado de juego en vivo: imagina un juego de ajedrez cuya lógica de bot externalizas a un LLM exponiendo un par de herramientas.

Dos cosas hacen que el modo de tiempo de ejecución sea diferente del modo de editor, y ambas son deliberadas:

Nunca se conecta automáticamente. El complemento del editor se conecta al iniciar; una compilación de juego no. Tú escribes el código de aceptación y decides cuándo (si acaso) llamar a Connect().
No hay herramientas, prompts ni recursos por defecto — estrictamente manual. El tiempo de ejecución incluye cero herramientas MCP, prompts y recursos. Registras cada herramienta [AiToolType], prompt [AiPromptType], y recurso [AiResourceType] tú mismo, en tu propio código — y cada tipo es independientemente opcional (registra prompts sin herramientas, o viceversa). (Las familias de herramientas del editor del addon están limitadas por #if TOOLS y ni siquiera se compilan en una compilación de juego, por lo que nunca pueden filtrarse).

El punto de entrada es GodotMcpRuntime.Initialize(...) (espacio de nombres com.IvanMurzak.Godot.MCP.Runtime). Escríbelo una vez — p. ej. desde el _Ready() de un autoload de Godot para que exista un SceneTree:

using System.Reflection;
using com.IvanMurzak.Godot.MCP.Connection;   // GodotMcpConnectionMode
using com.IvanMurzak.Godot.MCP.Runtime;      // GodotMcpRuntime
using McpServerConsts = com.IvanMurzak.McpPlugin.Common.Consts.MCP.Server;   // AuthOption (none/oauth/token)
using Godot;

public partial class GameMcp : Node
{
    private GodotMcpRuntimeHandle? _mcp;

    public override async void _Ready()
    {
        // 1) Build the connection (default OFF — nothing connects yet).
        _mcp = GodotMcpRuntime.Initialize(builder =>
        {
            builder.WithConfig(config =>
            {
                config.ConnectionMode = GodotMcpConnectionMode.Custom;         // your own server
                config.Host           = "http://localhost:8080";               // prefer loopback
                config.AuthOption     = McpServerConsts.AuthOption.token;      // offline bearer-token auth
                config.Token          = "your-secret-token";
            });

            // 2) Opt YOUR tools / prompts / resources in. Zero of each by default — this is the only way
            //    they get registered, and each kind is independently optional.
            builder.WithToolsFromAssembly(Assembly.GetExecutingAssembly());     // [AiToolType] classes
            builder.WithPromptsFromAssembly(Assembly.GetExecutingAssembly());   // [AiPromptType] classes
            builder.WithResourcesFromAssembly(Assembly.GetExecutingAssembly()); // [AiResourceType] classes
            //   …or register specific families:
            //   builder.WithTools(typeof(GameMcpTools));
            //   builder.WithPrompts(typeof(GameMcpPrompts));
            //   builder.WithResources(typeof(GameMcpResources));
        }).Build();

        // 3) Connect — explicit, the security-required opt-in. Retries in the background while
        //    KeepConnected is true (the default).
        await _mcp.Connect();
    }

    public override async void _ExitTree()
    {
        // 4) Disconnect on shutdown (or whenever you want to stop exposing tools).
        if (_mcp is not null)
            await _mcp.Disconnect();
    }
}

Superficie del constructor (todo fluido / encadenable):

Llamada	Qué hace
`GodotMcpRuntime.Initialize(configure)`	Comienza la configuración; devuelve un `GodotMcpRuntimeBuilder`. `configure` puede ser `null` para el valor predeterminado de cero herramientas y configurado por entorno.
`builder.WithConfig(Action<GodotMcpConfig>)`	Establece `Host` / `Token` / `ConnectionMode` / `AuthOption` en código. Múltiples llamadas se componen en orden.
`builder.WithToolsFromAssembly(Assembly)`	Registra cada clase `[AiToolType]` en un ensamblado (generalmente `Assembly.GetExecutingAssembly()`).
`builder.WithTools(params Type[])`	Registra clases `[AiToolType]` específicas cuando un escaneo de todo el ensamblado es demasiado amplio.
`builder.WithPromptsFromAssembly(Assembly)`	Registra cada clase `[AiPromptType]` en un ensamblado. Independiente de herramientas/recursos.
`builder.WithPrompts(params Type[])`	Registra clases `[AiPromptType]` específicas.
`builder.WithResourcesFromAssembly(Assembly)`	Registra cada clase `[AiResourceType]` en un ensamblado. Independiente de herramientas/prompts.
`builder.WithResources(params Type[])`	Registra clases `[AiResourceType]` específicas.
`builder.WithoutMainThreadDispatcher()`	Omite el arranque automático del despachador del hilo principal (solo si instalas tu propio despachador de autoload).
`builder.WithRuntimeErrorCapture()`	Captura errores generados en el juego en ejecución (errores de tiempo de ejecución de GDScript, `push_error`/`push_warning`, errores de shader a través del enganche del motor de Godot 4.5+; excepciones C# no controladas / no observadas de `Task` con trazas de pila completas) y registra la herramienta `runtime-errors-` para que un agente pueda consultarlas. DESACTIVADO por defecto.* Consulta "Captura de errores de tiempo de ejecución en el juego" a continuación.
`builder.Build()`	Finaliza; devuelve un `GodotMcpRuntimeHandle` DESACTIVADO por defecto.
`handle.Connect()` / `handle.Disconnect()`	Abre / cierra la conexión. `handle.Dispose()` la cierra al apagar.

Initialize().Build() también garantiza un despachador del hilo principal Node en el SceneTree en ejecución (para que los manejadores de herramientas puedan enviar llamadas a la API de Godot al hilo principal del motor), a menos que optes por no hacerlo con WithoutMainThreadDispatcher(). Llámala una vez que un SceneTree esté activo (p. ej. desde un _Ready de autoload).

Captura de errores de tiempo de ejecución en el juego

En modo editor, console-get-logs y script-validate muestran los registros propios del complemento y los errores de análisis de GDScript. Pero los errores generados dentro de un juego en ejecución — un error de tiempo de ejecución de GDScript (una desreferencia nula, un índice incorrecto), un push_error/push_warning, un error de shader o una excepción C# no controlada — no son visibles para un agente a través de esas herramientas del editor. Sin esto, un agente puede lanzar el juego, consultar registros, ver silencio y concluir erróneamente que el juego está sano. Esta es la brecha que bloquea un bucle no supervisado "seguir arreglando hasta que no haya errores" para errores reales de juego/tiempo de ejecución.

Opta por participar con WithRuntimeErrorCapture():

_mcp = GodotMcpRuntime.Initialize(builder =>
{
    builder.WithConfig(cfg => { /* host / token … */ });
    builder.WithRuntimeErrorCapture();   // capture in-game runtime errors + expose the runtime-errors-* tool
}).Build();

await _mcp.Connect();

Esa única llamada instala tres canales de captura de mejor esfuerzo y registra la herramienta runtime-errors-*:

Flujo de errores del motor (Godot 4.5+) — registra un Godot.Logger a través de OS.AddLogger, por lo que los errores de tiempo de ejecución de GDScript, push_error/push_warning y errores de shader generados en el juego en ejecución se capturan con su origen (file / line / function).
Excepciones C# no controladas — AppDomain.CurrentDomain.UnhandledException, con la traza de pila administrada completa.
Excepciones C# no observadas de Task — TaskScheduler.UnobservedTaskException, con la traza de pila administrada completa. (Solo observa para registrar — no llama a SetObserved(), por lo que el comportamiento de escalado propio de tu juego no cambia).

Un cliente MCP consulta los errores capturados con la herramienta runtime-errors-get (y limpia el búfer con runtime-errors-clear):

Herramienta Qué devuelve / hace

runtime-errors-get Una lista limitada, que conserva los más recientes, de { sequence, message, type, source, file, line, function, stackTrace, frames, timestamp }. Pasa el highestSequence del resultado anterior como sinceSequence para consultar solo errores nuevos — el bucle "¿se rompió algo desde la última vez que miré?". Devuelve available:false cuando la captura nunca se habilitó (para que una lista vacía nunca se confunda con salud).

runtime-errors-clear Limpia el búfer capturado (el contador monótono sequence se conserva, por lo que una consulta sinceSequence anterior a la limpieza aún se comporta correctamente).

Herramienta	Qué devuelve / hace
`runtime-errors-get`	Una lista limitada, que conserva los más recientes, de `{ sequence, message, type, source, file, line, function, stackTrace, frames, timestamp }`. Pasa el `highestSequence` del resultado anterior como `sinceSequence` para consultar solo errores nuevos — el bucle "¿se rompió algo desde la última vez que miré?". Devuelve `available:false` cuando la captura nunca se habilitó (para que una lista vacía nunca se confunda con salud).
`runtime-errors-clear`	Limpia el búfer capturado (el contador monótono `sequence` se conserva, por lo que una consulta `sinceSequence` anterior a la limpieza aún se comporta correctamente).

Fidelidad de la traza de pila (lee esto). Las dos fuentes de error difieren en profundidad:

Errores del motor (source: Engine) llevan el origen del error — file:line y el function de origen — más el mensaje y un type (Error / Warning / Script / Shader). En Godot 4.5+, un error de tiempo de ejecución de GDScript también lleva la traza de pila profunda de múltiples marcos: frames es el backtrace ordenado (del más interno al más externo) — cada { function, file, line } — y stackTrace es el renderizado formateado del motor. En Godot < 4.5 (o una compilación de lanzamiento sin seguimiento de pila de llamadas) frames es null y stackTrace es null (solo origen). Los marcos se materializan fuera del ScriptBacktrace no seguro para hilos del motor dentro de la devolución de llamada del registrador en el hilo de origen — solo valores administrados simples cruzan hacia el recolector, nunca un objeto vivo del motor.

Fallos C# (source: UnhandledException / UnobservedTaskException) llevan la traza de pila administrada completa (excepciones internas en línea) en stackTrace, más el nombre del tipo de excepción CLR en type. (frames es null — la pila administrada vive en la cadena stackTrace).

Degradación elegante. En Godot < 4.5 no hay enganche administrado OS.AddLogger, por lo que el canal del motor no está disponible silenciosamente — los canales de excepción C# aún funcionan, y runtime-errors-get aún funciona (solo que no verá errores de tiempo de ejecución de GDScript). Y como el resto del modo de tiempo de ejecución, la captura es estrictamente opcional — sin WithRuntimeErrorCapture() no se engancha nada y no hay cambio de comportamiento. Disponer del manejador (handle.Dispose()) desinstala los enganches. ⚠️ Seguridad — divulgación de información. Los errores capturados reenvían el mensaje completo y (para fallos de C#) el seguimiento de pila administrado completo al agente conectado a través de runtime-errors-get. Esas cadenas pueden incrustar datos sensibles del runtime — rutas absolutas del sistema de archivos, nombres de máquina/usuario, cadenas de consulta, o un secreto/token que apareció en un mensaje de excepción o argumento. Ese es el valor diagnóstico previsto, pero amplía lo que se expone a través de la conexión. Habilite WithRuntimeErrorCapture() solo en una conexión confiable: un host de bucle local (http://localhost:… / 127.0.0.1) con AuthOption = Consts.MCP.Server.AuthOption.token y un token real — nunca una interfaz pública no autenticada en una compilación de lanzamiento. Consulte Seguridad y docs/runtime-security.md.

Ejemplo: una herramienta de estado de juego en vivo

Una herramienta de runtime se escribe exactamente como una herramienta de editor — un partial class decorado [AiToolType], cada método decorado [AiTool("tool-name", …)] con un [Description] en el método y cada parámetro. Cualquier llamada a la API de Godot (Node, SceneTree, …) debe ejecutarse en el hilo principal del motor — mársela a través de MainThread.Instance.Run(...) (el MainThread de ReflectorNet, respaldado por el despachador Initialize() inicializado por usted).

Este análogo de Godot del ejemplo "Chess bot" de Unity-MCP expone el SceneTree en ejecución en vivo al LLM — un viaje de ida y vuelta game-ping puramente administrado más un game-scene-tree-summary que lee el estado real de Node:

using System.ComponentModel;
using com.IvanMurzak.McpPlugin;              // [AiToolType], [AiTool]
using com.IvanMurzak.ReflectorNet.Utils;     // MainThread
using Godot;

[AiToolType]
public partial class GameMcpTools
{
    [AiTool("game-ping", Title = "Game Ping", ReadOnlyHint = true, IdempotentHint = true)]
    [Description("Runtime readiness probe. Echoes 'message' back, or returns 'pong-from-game' when omitted.")]
    public string GamePing(
        [Description("Optional message to echo back. When null/empty, returns 'pong-from-game'.")]
        string? message = null)
    {
        return string.IsNullOrEmpty(message) ? "pong-from-game" : message;
    }

    [AiTool("game-scene-tree-summary", Title = "Game Scene-Tree Summary", ReadOnlyHint = true)]
    [Description("Summary of the LIVE running game's SceneTree (current scene + root child node names).")]
    public SceneTreeSummary GameSceneTreeSummary()
    {
        // Touch the live SceneTree on the engine main thread — MainThread.Instance was installed by
        // GodotMcpRuntime.Initialize(...). Touching Node APIs off the main thread would fault.
        return MainThread.Instance.Run(() =>
        {
            var summary = new SceneTreeSummary();
            if (Engine.GetMainLoop() is not SceneTree tree || tree.Root == null)
            {
                summary.CurrentSceneName = "<no-scene-tree>";
                return summary;
            }

            summary.CurrentSceneName = tree.CurrentScene?.Name ?? "<none>";
            summary.RootChildCount   = tree.Root.GetChildCount();
            foreach (var child in tree.Root.GetChildren())
                summary.RootChildNames.Add(child.Name);
            return summary;
        });
    }
}

// Structured result (ReflectorNet-serialized — never ad-hoc string formatting for parseable output).
public sealed class SceneTreeSummary
{
    public string CurrentSceneName { get; set; } = string.Empty;
    public int RootChildCount { get; set; }
    public System.Collections.Generic.List<string> RootChildNames { get; set; } = new();
}

Regístrelo desde el bloque Initialize(...) anterior (WithToolsFromAssembly(Assembly.GetExecutingAssembly()) lo recoge automáticamente), conéctese, y el LLM ahora puede llamar a game-ping / game-scene-tree-summary contra su juego en vivo. Ejemplo real de subcontratación de lógica de bot: una herramienta chess-do-turn que llama a su controlador de juego en el hilo principal, más una herramienta chess-get-board que devuelve un modelo de tablero estructurado.

Mismo contrato [AiToolType]/[AiTool]/MainThread.Instance.Run(...) que la sección de Personalizar Herramientas del editor — la única diferencia es que en una compilación de juego usted registra las herramientas y usted llama a Connect().

Ejemplo: un prompt y un recurso

Las herramientas no son lo único que puede exponer — MCP también tiene prompts (plantillas de instrucciones reutilizables que un LLM puede solicitar por nombre) y recursos (contenido direccionable y de solo lectura que el LLM puede obtener por URI). Se registran exactamente como las herramientas: un partial class decorado [AiPromptType] / [AiResourceType], con cada miembro decorado [AiPrompt(...)] / [AiResource(...)] y un [Description]. Registre sus clases de prompt y recurso de la misma manera que registra herramientas — WithPromptsFromAssembly(...) / WithResourcesFromAssembly(...) (o el WithPrompts(...) / WithResources(...) por tipo) desde el bloque Initialize(...) anterior. Cada tipo es independientemente opcional — un juego puede exponer prompts y/o recursos sin ninguna herramienta.

using System.ComponentModel;
using com.IvanMurzak.McpPlugin;               // [AiPromptType], [AiPrompt], [AiResourceType], [AiResource]
using com.IvanMurzak.McpPlugin.Common.Model;  // Role, ResponseResourceContent
using com.IvanMurzak.ReflectorNet.Utils;      // MainThread
using Godot;

// A PROMPT — a named, reusable instruction the LLM can request. Returns the prompt text; Role marks who
// the message is from. Set Enabled = false to ship a prompt registered-but-off until you flip it on.
[AiPromptType]
public partial class GameMcpPrompts
{
    [AiPrompt(Name = "explain-game-state", Role = Role.User)]
    [Description("Ask the assistant to summarize the current game state for the player.")]
    public string ExplainGameState()
    {
        return "Read the live SceneTree via the game tools and explain the current game state in one paragraph.";
    }
}

// A RESOURCE — addressable read-only content fetched by URI. Route is the URI template; the method
// returns ResponseResourceContent[]. Any Godot API access marshals onto the main thread, exactly like a tool.
[AiResourceType]
public partial class GameMcpResources
{
    [AiResource(
        Name = "Live SceneTree node names",
        Route = "game://scene-tree/nodes",
        MimeType = "application/json",
        Description = "The root child node names of the live running game's SceneTree.")]
    public ResponseResourceContent[] SceneTreeNodes(string uri)
    {
        return MainThread.Instance.Run(() =>
        {
            var names = new System.Collections.Generic.List<string>();
            if (Engine.GetMainLoop() is SceneTree tree && tree.Root != null)
            {
                foreach (var child in tree.Root.GetChildren())
                    names.Add(child.Name);
            }

            var json = System.Text.Json.JsonSerializer.Serialize(names);
            return new[] { ResponseResourceContent.CreateText(uri, json, "application/json") };
        });
    }
}

Mismo contrato de registro manual independientemente opcional que las herramientas. Los nombres de atributos [AiPrompt]/[AiResource], el enum Role y el helper ResponseResourceContent provienen del paquete com.IvanMurzak.McpPlugin reutilizado que la ruta del editor ya usa — nada específico de Godot que aprender.

De dónde provienen la URL del servidor y el token

Una compilación de juego nunca carga automáticamente la configuración guardada del editor (eso es una conveniencia solo del editor). Usted proporciona el host/token de una de dos maneras — y se componen, con el entorno ganando sobre el código en el momento de la resolución:

En código — builder.WithConfig(c => { c.Host = …; c.Token = …; }), como arriba.

Fuera de banda — variables de entorno del proceso GODOT_MCP_* o un archivo .env del proyecto (leído en vivo por GodotMcpConfig, para que una compilación pueda reconfigurarse sin recompilar):

Variable de entorno	Valores	Descripción
`GODOT_MCP_CONNECTION_MODE`	`Cloud` / `Custom`	Modo de conexión (un host de bucle local implica `Custom`).
`GODOT_MCP_CLOUD_URL`	URL	Anula la URL base de Cloud (predeterminado `https://ai-game.dev`).
`GODOT_MCP_HOST`	URL	Host del servidor en modo personalizado (predeterminado `http://localhost:8080`).
`GODOT_MCP_AUTH_OPTION`	`none` / `oauth` / `token`	Autenticación en modo personalizado: anónimo / cuenta (oauth) / portador fuera de línea (`token`).
`GODOT_MCP_TOKEN`	cadena	El token de portador (enrutado a Cloud o Personalizado según el modo activo).
`GODOT_MCP_LOG_LEVEL`	`Trace`…`None`	Umbral de verbosidad de registro.
`GODOT_MCP_SERVER_PATH`	ruta absoluta	Solo editor (dev / CI). Inicie este `gamedev-mcp-server(.exe)` existente en lugar de la versión fijada: omite la descarga y la coincidencia de versión, y deshabilita la limpieza de servidores huérfanos mientras esté activo. Un valor que no nombre un archivo existente se ignora.

GODOT_MCP_SERVER_PATH es resuelto por el administrador de servidores del complemento del editor, no por GodotMcpConfig, por lo que solo afecta a qué binario de servidor alojado localmente inicia el editor, y no tiene efecto en una compilación de juego. Se lee una vez por carga de ensamblado del complemento y se almacena en caché — una recarga en caliente de C# lo vuelve a leer, pero alternar el complemento de encendido a apagado no. Usa la misma precedencia de entorno de proceso → .env del proyecto que las filas anteriores. La limpieza de huérfanos está deshabilitada mientras esté configurado porque esa limpieza reclama cada proceso de servidor que se ejecuta desde el mismo directorio, que se espera que un binario de anulación comparta con otros proyectos y herramientas. Un valor que no nombre un archivo existente se ignora con una advertencia en el registro del editor. En Linux/macOS el archivo ya debe ser ejecutable — el chmod aplicado a una versión descargada no se aplica a un binario de anulación.

export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:8080
export GODOT_MCP_AUTH_OPTION=token
export GODOT_MCP_TOKEN=your-secret-token

Modo Cloud (GodotMcpConnectionMode.Cloud) se conecta a https://ai-game.dev (anule con GODOT_MCP_CLOUD_URL).
Modo personalizado (GodotMcpConnectionMode.Custom) se conecta a su propio servidor — un servidor de desarrollo local, autoalojado o una dirección de bucle local. Este es el modo recomendado para un juego publicado (ver más abajo).

Seguridad: solo opt-in, DESACTIVADO por defecto

Exponer un servidor MCP dentro de un juego publicado abre una superficie de control remoto: cualquier cosa que sus herramientas registradas puedan hacer, un cliente MCP conectado puede impulsarla. El runtime de Godot-MCP está construido para que esto solo pueda suceder deliberadamente:

Solo opt-in / DESACTIVADO por defecto. Crear un manejador no se conecta. No sucede nada hasta que su código llama a Connect(). No hay ruta de auto-conexión en una compilación de juego.
Cero herramientas por defecto. Un runtime sin llamada a WithTools… registra nada. La superficie de ataque es exactamente el conjunto de herramientas que eligió registrar — nada más.
Sin carga automática de configuración persistida. Una compilación de juego nunca lee silenciosamente un archivo de configuración guardado; el host/token provienen solo de su código o de GODOT_MCP_* env / .env.
Prefiera bucle local + un token requerido. Para herramientas locales, vincúlese a un host de bucle local (http://localhost:… / 127.0.0.1) y configure AuthOption = Consts.MCP.Server.AuthOption.token con un Token real. Evite exponer la conexión en una interfaz pública en una compilación de lanzamiento a menos que haya diseñado y asegurado explícitamente esa superficie.
La captura de errores de runtime reenvía datos sensibles. WithRuntimeErrorCapture() está DESACTIVADO por defecto. Cuando se habilita, los mensajes capturados y los seguimientos de pila se envían textualmente al agente conectado a través de runtime-errors-get y pueden contener rutas absolutas, nombres de máquina/usuario o un secreto que apareció en una excepción — así que habilítelo solo en una conexión confiable de bucle local + token (nota completa bajo Capturando errores de runtime en el juego).

Notas de seguridad del lado del editor (postura aceptada)

Los puntos anteriores son sobre una compilación de juego. Dos superficies del lado del editor se documentan aquí para completitud; ambas son por diseño hoy:

El almacenamiento de tokens del editor es texto plano en reposo. Cuando conecta el complemento del editor (autenticación de dispositivo Cloud o un token de modo personalizado), el complemento persiste su configuración de conexión — incluido el token de portador (token) y el token de Cloud (cloudToken) — como JSON en texto plano en user://godot-mcp-config.json (resuelto según el directorio de datos de user:// de Godot). No está cifrado ni almacenado en un almacén de claves del sistema operativo. La suposición de confianza es la cuenta de usuario local: cualquier persona con acceso de lectura a su directorio de datos de usuario puede leer el token. Trate ese archivo como un secreto — no lo confirme, sincronice ni comparta. Para rotar, borre el token guardado en el panel (o elimine el archivo) y vuelva a conectarse. (Las anulaciones de entorno de proceso / .env a través de GODOT_MCP_TOKEN siempre eclipsan el valor persistido y no se escriben de vuelta en este archivo.)
El puente de control de desarrollo no está autenticado pero está desactivado por compuerta. Existe un puente HTTP de inyección/control solo de desarrollo para impulsar el panel del editor en pruebas. No está autenticado, pero su límite de seguridad es triple: es solo del editor (#if TOOLS, nunca compilado en un juego), se vincula solo a 127.0.0.1, y se inicia solo cuando GODOT_MCP_DEV_CONTROL=1 — un complemento publicado (y cualquier sesión de editor sin la variable de entorno) nunca escucha. Esa compuerta de entorno es fundamental y está aplicada por una prueba unitaria + una aserción de tiempo de arranque, por lo que nunca puede enviarse silenciosamente habilitada.

Una copia independiente corta de este contrato vive en docs/runtime-security.md.

AI Game Developer — Godot MCP

Cómo funciona la arquitectura de Godot MCP

Godot-MCP es un puente entre LLMs y el editor de Godot. Expone y explica las herramientas de Godot al LLM, que luego entiende la interfaz y usa las herramientas según sus solicitudes.

Al cargar el editor, el [Tool] EditorPlugin (GodotMcpPlugin) inicia el complemento: instala un despachador de hilo principal, construye un ReflectorNet Reflector con convertidores de tipos de Godot, y abre una conexión SignalR a un servidor MCP a través del cliente com.IvanMurzak.McpPlugin reutilizado. Las herramientas de IA que registra son entonces invocables por cualquier agente de IA compatible con MCP.

Qué es `MCP`

MCP — Protocolo de Contexto de Modelo. En pocas palabras, es USB Type-C para IA, específicamente para LLMs (Modelos de Lenguaje Grande). Enseña al LLM cómo usar características externas — como el Motor Godot en este caso, o incluso su propio método C# personalizado. Documentación oficial.

Qué es un `AI agent`

Es una aplicación con una ventana de chat. Puede tener agentes inteligentes para operar mejor, y herramientas MCP avanzadas integradas. Un cliente MCP bien construido es el 50% del éxito de la IA en ejecutar una tarea — por eso es importante elegir uno bueno.

Qué es el `MCP Server`

Es el puente entre el MCP Client y "algo más" — en este caso el editor de Godot. En modo Cloud este es el backend alojado de ai-game.dev; en modo Personalizado es el host compartido GameDev-MCP-Server que usted mismo ejecuta (o deja que el complemento descargue y ejecute por usted).

Qué es un `MCP Tool`

Un MCP Tool es una función que el LLM puede llamar para interactuar con Godot. Estas herramientas son el puente entre solicitudes en lenguaje natural y operaciones reales de Godot. Cuando le pide a la IA que "cree un nodo" o "abra una escena", usa herramientas MCP para ejecutar la acción. Las herramientas tienen parámetros tipados y descritos; devuelven resultados estructurados; y son conscientes de los hilos (hilo principal para llamadas a la API de Godot, hilo de fondo para procesamiento pesado).

AI Game Developer — Godot MCP

Compilación y contribución

Godot.NET.Sdk es un SDK de NuGet, por lo que no se requiere un binario de Godot para compilar o probar unitariamente:

dotnet restore Godot-MCP.sln
dotnet build  Godot-MCP.sln --configuration Debug --no-restore   # 0 errors required (CI gate)
dotnet test   Godot-MCP.Tests/Godot-MCP.Tests.csproj --configuration Debug --no-build

Solo se necesita un editor de Godot 4.3+ para la verificación conductual en vivo de las herramientas que impulsan el motor. Consulte CLAUDE.md para el manual completo de compilación/prueba/ejecución, la corrección de carga de ensamblados editor-runtime, convenciones y la prueba de humo del banco de pruebas sin cabeza.

Las contribuciones son muy apreciadas. ¡Por favor, dé una estrella a este proyecto 🌟 si le resulta útil!

👉 Haz un fork del proyecto
Clona el fork y ábrelo en un editor de Godot 4.3+ (mono)
Implementa cosas nuevas, haz commit y sube a GitHub
Crea un Pull Request dirigido al repositorio original Godot-MCP, rama main.

Godot-MCP

Documentación

✨ Desarrollador de Juegos con IA — Godot MCP

Inicio Rápido

Contenido

Referencia de Herramientas

Requisitos

Instalación

Paso 1: Agrega el addon

Opción A — Biblioteca de Activos de Godot (recomendada)

Opción B — Zip de la versión de GitHub

Opción C — Copiar desde el código fuente

Paso 2: Agrega los paquetes NuGet + la incrustación del catálogo de extensiones

Paso 3: Instala un agente de IA

Conectar

Modo Nube (predeterminado) — ai-game.dev

Modo Personalizado — tu propio servidor

Configuración de Godot MCP Server

Servidor local — deja que el addon lo descargue y ejecute por ti

Ejecutar el servidor manualmente (avanzado)

Personalizar herramientas

Uso en tiempo de ejecución (en el juego)

Captura de errores de tiempo de ejecución en el juego

Ejemplo: una herramienta de estado de juego en vivo

Ejemplo: un prompt y un recurso

De dónde provienen la URL del servidor y el token

Seguridad: solo opt-in, DESACTIVADO por defecto

Notas de seguridad del lado del editor (postura aceptada)

Cómo funciona la arquitectura de Godot MCP

Qué es MCP

Qué es un AI agent

Qué es el MCP Server

Qué es un MCP Tool

Compilación y contribución

Licencia

Configuración de Godot `MCP Server`

Qué es `MCP`

Qué es un `AI agent`

Qué es el `MCP Server`

Qué es un `MCP Tool`