GoPeak

El servidor MCP más completo para Godot Engine. Más de 95 herramientas para gestión de escenas, GDScript LSP, depuración DAP, captura de pantallas, inyección de entrada y biblioteca de activos CC0.

GitHub

240

Prueba este MCPPatrocinado

Documentación

GoPeak

GoPeak Hero

GoPeak es un servidor MCP para Godot 4 que brinda a los asistentes de IA un bucle real de editar → ejecutar → inspeccionar → corregir.

Está diseñado para flujos de trabajo confiables de Godot 4: superficie de herramientas predeterminada pequeña, capacidades avanzadas restringidas por configuración y reglas de compatibilidad explícitas para nombres de herramientas antiguos/heredados.

El inglés es la fuente canónica de verdad. Los README localizados son resúmenes concisos y pueden quedar desactualizados respecto a README.md.

Discord no está disponible temporalmente mientras se actualiza el enlace de invitación. Usa GitHub Discussions por ahora.

Inicio rápido

Requisitos

Godot 4.x
Bun 1.3.3+
Cliente compatible con MCP como Claude Desktop, Cursor, Cline u OpenCode

1) Instalar GoPeak

bun add -g https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz

Ese es el método de instalación más rápido. Instala el runtime incluido directamente desde GitHub Releases sin npm. Para una instalación verificada por checksum, usa:

curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz
curl -fLO https://github.com/HaD0Yun/Doyunha-Gopeak/releases/download/v2.3.9/gopeak-2.3.9.tgz.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c gopeak-2.3.9.tgz.sha256
else
  shasum -a 256 -c gopeak-2.3.9.tgz.sha256
fi
bun add -g "$PWD/gopeak-2.3.9.tgz"

La ruta verificada comprueba la descarga antes de que Bun la instale globalmente. La ruta absoluta del tarball evita un error de ruta relativa en Bun 1.3.3. El comando de checksum funciona en Linux (sha256sum) y macOS (shasum). Para usar el instalador compatible en su lugar, descarga o clona el repositorio y ejecútalo localmente; no canalices un script remoto a un shell:

git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
./install.sh

El archivo de lanzamiento contiene el runtime incluido. La instalación y ejecución no contactan con el registro npm ni requieren credenciales npm. Para una verificación de procedencia más sólida, los revisores de lanzamientos también pueden verificar la atestación de artefactos de GitHub como se describe en el proceso de lanzamiento.

Si usaste el instalador antiguo, --dir, --godot y --configure siguen siendo aceptados con advertencias hasta la línea 2.3.x y se planea eliminarlos en 3.0.0. Los nuevos mapeos son: usa el directorio global de Bun (BUN_INSTALL) en lugar de un directorio de checkout de código fuente, coloca GODOT_PATH en el env del cliente MCP y usa la configuración a continuación en lugar de depender de la salida del instalador. Durante la ventana de compatibilidad, --godot y --configure aún imprimen un fragmento de cliente pero nunca escriben archivos de cliente. Consulta la política de migración para conocer el contrato exacto.

2) Añadir configuración del cliente MCP

{
  "mcpServers": {
    "godot": {
      "command": "gopeak",
      "args": [],
      "env": {
        "GODOT_PATH": "/path/to/godot",
        "GOPEAK_TOOL_PROFILE": "compact"
      }
    }
  }
}

compact es el perfil predeterminado. Mantiene el contexto MCP inicial pequeño y expone grupos adicionales con restricciones de configuración solo cuando se solicitan.

3) Prueba estos prompts

"Lista los proyectos de Godot en /your/projects y muestra la información del proyecto."
"Crea scenes/Player.tscn con una raíz CharacterBody2D y un script de movimiento."
"Ejecuta el proyecto, lee la salida de depuración y corrige el error principal."
"Usa tool.catalog para encontrar herramientas de animación y luego activa el grupo correcto."

Qué obtienes

Flujo de trabajo	Qué puede hacer GoPeak
Control de proyectos	Encuentra proyectos, lanza el editor, ejecuta/detiene el juego, recopila salida de depuración.
Edición de escenas y scripts	Crea escenas, añade nodos, edita propiedades tipadas, crea/modifica GDScript.
Flujos de trabajo de recursos	Trabaja con recursos, materiales, shaders, importaciones y comprobaciones relacionadas con la exportación.
Depuración	Usa registros, diagnósticos de Godot LSP, puntos de interrupción/trazas de pila de DAP e inspección en tiempo de ejecución cuando esté configurado.
Pruebas en tiempo de ejecución	Captura capturas de pantalla, inspecciona árboles en vivo, inyecta entrada y llama métodos de runtime a través del addon.
Descubrimiento de herramientas	Mantén la superficie predeterminada compacta y luego activa grupos de capacidades con `tool.catalog` o `tool.groups`.

Puertas de configuración

Algunas capacidades requieren servicios adicionales del lado de Godot. GoPeak las etiqueta en lugar de pretender que todo está siempre disponible:

Capacidad	Requiere
Ediciones de escena/recurso del puente del editor	Plugin `godot_mcp_editor` habilitado en el proyecto de Godot.
Inspección en tiempo de ejecución, capturas de pantalla, inyección de entrada	Addon/socket de runtime, puerto predeterminado `7777`.
Herramientas LSP de GDScript	Godot LSP habilitado en el puerto `6005`.
Herramientas de depuración DAP	Godot DAP habilitado en el puerto `6006`.
Herramientas de tienda/proveedor de activos	Acceso a red y disponibilidad del proveedor.

Añadir los plugins de Godot

Instala desde la carpeta de tu proyecto de Godot:

curl -sL https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.sh | bash

PowerShell:

iwr https://raw.githubusercontent.com/HaD0Yun/Doyunha-Gopeak/main/install-addon.ps1 -UseBasicParsing | iex

Luego habilita los plugins en Configuración del proyecto → Plugins:

godot_mcp_editor para herramientas de escena/recurso respaldadas por el puente
godot_mcp_runtime para inspección en tiempo de ejecución, capturas de pantalla y flujos de entrada

Los ganchos de shell opcionales para notificaciones de actualización son opcionales:

gopeak setup

gopeak setup solo modifica los archivos rc de bash/zsh compatibles cuando lo ejecutas explícitamente. Instalar el activo de lanzamiento no añade ganchos de shell automáticamente.

Perfiles de herramientas

GoPeak admite tres perfiles de exposición:

Perfil	Úsalo cuando
`compact`	Predeterminado. Herramientas principales confiables más grupos dinámicos activados bajo demanda.
`full`	Modo de compatibilidad/auditoría para la superficie heredada completa.
`legacy`	Alias de configuración antiguo con el mismo comportamiento expuesto que `full`.

Establece GOPEAK_TOOL_PROFILE o el alias de respaldo MCP_TOOL_PROFILE.

Grupos dinámicos

En modo compacto, busca con tool.catalog; los grupos coincidentes se activan automáticamente. También puedes gestionar grupos directamente con tool.groups.

Grupos comunes:

Grupo	Estado	Notas
`runtime`	runtime opcional	Árbol de escena en vivo, propiedades, llamadas a métodos, métricas. Requiere addon/socket de runtime.
`testing`	runtime opcional	Capturas de pantalla, captura de viewport, inyección de entrada. Requiere configuración de runtime/editor.
`lsp`	lsp opcional	Diagnósticos, autocompletado, hover, símbolos. Requiere Godot LSP en el puerto `6005`.
`dap`	dap opcional	Puntos de interrupción, ejecución paso a paso, trazas de pila. Requiere Godot DAP en el puerto `6006`.
`asset_store`	red opcional	Búsqueda/descarga de activos CC0 externos. Depende de red/proveedor.
`class_advanced`	estático confiable	Descubrimiento de ClassDB/herencia respaldado por metadatos estáticos del motor.
`tilemap`	requiere auditoría	Debe tener en cuenta el comportamiento de Godot 4.3+ `TileMapLayer` antes de la promoción.
grupos de mutación	requiere auditoría	Los grupos de escena/recurso/script/configuración/señal/autoload/importación/audio/navegación/tema/animación necesitan evidencia de fixture antes de comercializarse como totalmente confiables.
`intent_tracking`	capa de flujo de trabajo	Ayudantes de memoria/transferencia de flujo de trabajo, no una primitiva del motor de Godot. Mantener opcional.

Si tu cliente MCP no se actualiza después de la activación, reconecta el cliente o llama una vez a la herramienta recién activada para forzar un nuevo viaje de ida y vuelta de tools/list.

GoPeak también usa paginación basada en cursor para tools/list para que los perfiles grandes no se vuelquen en el contexto de una vez. Ajústalo con GOPEAK_TOOLS_PAGE_SIZE cuando sea necesario.

Valores tipados de Godot

Las herramientas de escena respaldadas por el puente, como add_node y set_node_properties, aceptan cargas útiles de vectores comunes para propiedades tipadas:

{
  "position": { "type": "Vector2", "x": 100, "y": 200 },
  "scale": { "type": "Vector2", "x": 2, "y": 2 }
}

Los { "x": 100, "y": 200 } y [100, 200] simples también se convierten para campos comunes de Vector2, pero los valores etiquetados son los más seguros entre herramientas.

Comandos útiles

# run the globally installed CLI
gopeak

# run from source
git clone https://github.com/HaD0Yun/Doyunha-Gopeak.git
cd Doyunha-Gopeak
bun ci
bun run build
bun run ./build/index.js

# local verification
bun run ci
bun run test:dynamic-groups
bun run test:metadata
bun run test:packaging

Nombres de binarios CLI:

gopeak
godot-mcp

Entorno y puertos

Nombre	Propósito	Predeterminado
`GOPEAK_TOOL_PROFILE`	Perfil de exposición de herramientas: `compact`, `full`, `legacy`	`compact`
`MCP_TOOL_PROFILE`	Alias de entorno de perfil de respaldo	`compact`
`GODOT_PATH`	Ruta explícita del ejecutable de Godot	auto-detección
`GODOT_BRIDGE_PORT`	Anulación del puerto HTTP+WS del puente/visualizador	`6505`
`GOPEAK_BRIDGE_HOST`	Host de enlace del puente/visualizador	`127.0.0.1`
`GOPEAK_TOOLS_PAGE_SIZE`	Número de herramientas por página de `tools/list`	`33`
`GOPEAK_RUNTIME_TIMEOUT_MS`	Tiempo de espera del comando del addon de runtime en milisegundos	`10000`
`DEBUG`	Habilitar registros de depuración del servidor	`false`
`LOG_MODE`	Modo de grabación: `lite` o `full`	`lite`

Puerto	Servicio
`6505`	Servidor unificado de Godot Bridge + Visualizer en loopback por defecto.
`6005`	Godot LSP.
`6006`	Godot DAP.
`7777`	Socket de comandos del addon de runtime.

Las herramientas de captura de pantalla en tiempo de ejecución (capture_screenshot, capture_viewport) usan un archivo PNG temporal gestionado por GoPeak cuando el addon de runtime admite output_path, y luego devuelven contenido de imagen MCP normal. Los addons de runtime más antiguos que no reciben un output_path continúan devolviendo capturas de pantalla base64 en línea.

Solución de problemas

Godot no encontrado → establece GODOT_PATH.
No se ven herramientas MCP → reinicia tu cliente MCP.
Necesitas una herramienta oculta → busca con tool.catalog o activa un grupo con tool.groups.
Ruta de proyecto no válida → confirma que project.godot existe.
Las herramientas de runtime no funcionan → instala/habilita el addon de runtime y verifica el puerto 7777.
Las capturas de pantalla de runtime agotan el tiempo → actualiza el addon de runtime para que los comandos de captura admitan el flujo gestionado de output_path. Para respuestas lentas de runtime, aumenta GOPEAK_RUNTIME_TIMEOUT_MS; los addons antiguos pueden seguir agotando el tiempo con capturas base64 en línea grandes.
Puente del editor desconectado → detén servidores duplicados de gopeak/MCP que ya puedan tener el puerto del puente 6505; get_editor_status informa errores de inicio del puente como EADDRINUSE.

Política de migración y desaprobación

GoPeak trata compact como el predeterminado seguro y full/legacy como perfiles de compatibilidad. Los cambios futuros de ocultar, eliminar, renombrar o contrato de API deben incluir:

mapeo de antiguo → nuevo o una nota explícita de sin reemplazo;
impacto en el perfil (compact, full, legacy o grupo opcional);
ventana de alias y momento de eliminación planificado;
actualizaciones de README/documentación y notas de lanzamiento;
verificación que demuestre la exposición de tools/list y el comportamiento de alias;
ejemplos de prompts de migración para flujos de trabajo comunes de Godot.

Postura actual: los nombres de herramientas heredados y los alias compactos siguen siendo compatibles. Los grupos externos opcionales (runtime, testing, lsp, dap, asset_store) están restringidos por configuración, no son un comportamiento central siempre disponible.

Política completa: docs/migration-policy.md.

Más documentación

Licencia y créditos

MIT — consulta LICENSE.

Servidor MCP original por Coding-Solo
Mejoras de GoPeak por HaD0Yun
Visualizador de proyectos inspirado en tomyud1/godot-mcp