godot-mcp-pilot

Servidor del Protocolo de Contexto de Modelo (MCP) para Godot 4 — Otorga a los asistentes de IA (Claude, Cursor, Cline, etc.) control directo sobre tus proyectos de Godot.

godot-mcp-pilot expone las operaciones del motor Godot como herramientas MCP, permitiendo a los asistentes de IA iniciar el editor, ejecutar proyectos, crear y editar escenas, escribir GDScript e inspeccionar activos, todo mediante lenguaje natural. Funciona tanto para juegos 2D como 3D.

"Create a CharacterBody3D player scene with a Camera3D and collision"
"Run the project and show me any errors"
"Add a DirectionalLight3D to the scene"
"Create a 2D platformer with sprites and tilemaps"

Inicio rápido

1. Instalación

npm install -g godot-mcp-pilot

O úsalo sin instalar:

npx godot-mcp-pilot

2. Ejecuta el asistente de configuración

npx godot-mcp-pilot setup
# or, if installed globally:
godot-mcp-pilot-setup

El asistente:

• Detectará automáticamente tu binario de Godot (revisa Aplicaciones, Descargas, PATH)

• Preguntará qué cliente de IA utilizas

• Escribirá la configuración en el lugar correcto para ese cliente

Configuración manual

Claude Code (CLI / Extensión de IDE)

Crítico: Claude Code lee .mcp.json desde el directorio donde lo ejecutas. El archivo debe estar en la carpeta de tu proyecto de juego, no en la carpeta godot-mcp-pilot.

# From inside your game project directory:
claude mcp add godot -- npx godot-mcp-pilot

Esto escribe .mcp.json en tu directorio actual. Luego, ejecuta siempre Claude Code desde ese directorio:

cd ~/games/my-platformer
claude

Si Godot no se detecta automáticamente (ej. nunca lo moviste de ~/Downloads):

claude mcp add godot -e GODOT_PATH=/path/to/Godot.app/Contents/MacOS/Godot -- npx godot-mcp-pilot

O escribe .mcp.json manualmente en la raíz de tu proyecto de juego:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-pilot"],
      "env": {
        "GODOT_PATH": "/path/to/your/Godot"
      }
    }
  }
}

Claude Desktop

Claude Desktop utiliza un archivo de configuración diferente — no lee .mcp.json.

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-pilot"],
      "env": {
        "GODOT_PATH": "/path/to/your/Godot"
      }
    }
  }
}

Luego cierra y vuelve a abrir Claude Desktop.

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["godot-mcp-pilot"],
      "env": {
        "GODOT_PATH": "/path/to/your/Godot"
      }
    }
  }
}

Detección de la ruta de Godot

El servidor busca automáticamente en estas ubicaciones (en orden):

Si la detección automática falla, establece GODOT_PATH a la ruta absoluta de tu ejecutable de Godot.

Juegos 2D y 3D

godot-mcp-pilot funciona igual de bien para 2D y 3D. Utiliza los tipos de nodo apropiados:

Ejemplos de prompts:

"Create a 3D scene with a Node3D root, MeshInstance3D floor, and DirectionalLight3D"
"Add a CharacterBody3D with a CollisionShape3D using a CapsuleShape3D"
"Write a GDScript for 3D first-person movement"

Características

Configuración

Solución de problemas

"MCP server not connected" / las herramientas no aparecen

Claude Code: El archivo .mcp.json debe estar en el directorio donde ejecutas claude. Abre una terminal nueva, entra (cd) en tu proyecto de juego y ejecuta claude desde allí.

Claude Desktop: Asegúrate de haber editado el archivo correcto (claude_desktop_config.json, no .mcp.json) y de haber cerrado y vuelto a abrir la aplicación por completo.

Godot no encontrado

Establece GODOT_PATH explícitamente en el bloque env de la configuración. En macOS, si descargaste Godot pero nunca lo moviste:

GODOT_PATH=/Users/yourname/Downloads/Godot.app/Contents/MacOS/Godot

Para encontrar dónde está Godot:

# macOS / Linux
find ~/Downloads ~/Applications /Applications -name "Godot" -type f 2>/dev/null

Errores de análisis de escena / .tscn mal formado

Si Godot se niega a cargar una escena editada por el MCP, verifica que las líneas instance= no tengan comillas:

# Correct
instance=ExtResource("1_abc")

# Wrong (Godot rejects this)
instance="ExtResource(\"1_abc\")"

Ejecuta el proyecto en modo headless para ver el error exacto:

/path/to/Godot --path /path/to/project --headless --quit 2>&1

El MCP se desconecta durante una sesión

Este es un problema conocido con algunas implementaciones de host MCP. Solución: cierra y vuelve a abrir tu cliente de IA. El servidor MCP en sí no tiene estado; reconectarse es seguro.

Flujos de trabajo de ejemplo

Shooter 2D de vista cenital

"Create a 2D scene called Main.tscn"
"Add a CharacterBody2D called Player at the center"
"Create a movement + shooting script for the Player"
"Add an Area2D called Enemy that moves toward the player"
"Run the project and show errors"

Plataformas 3D

"Create a 3D scene with a StaticBody3D floor (MeshInstance3D box, scale 20x1x20)"
"Add a CharacterBody3D player with a CapsuleShape3D collision"
"Create a 3D character controller script with jump and gravity"
"Add a Camera3D as a child of the player with offset Vector3(0, 2, 5)"

Modo de solo lectura

READ_ONLY_MODE=true npx godot-mcp-pilot

Deshabilita todas las herramientas de escritura. Útil para flujos de trabajo de CI/CD o revisión.

Desarrollo

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

# Run the setup wizard
npm run setup

# Development mode (ts-node, no build step)
npm run dev

Estructura del proyecto

godot-mcp-pilot/
├── src/
│   ├── index.ts               # Entry point
│   ├── server.ts              # MCP server + tool routing
│   ├── config.ts              # Godot path detection, env config
│   ├── godot-process.ts       # Process management (spawn, capture)
│   ├── tools/
│   │   ├── system.ts          # Version, project listing/info
│   │   ├── execution.ts       # Launch editor, run/stop project
│   │   ├── scene.ts           # Scene CRUD + node manipulation
│   │   ├── script.ts          # GDScript read/write/analyze
│   │   ├── assets.ts          # Asset listing/inspection
│   │   ├── project_settings.ts # Settings, autoloads, input maps
│   │   └── uid.ts             # Godot 4 UID management
│   └── utils/
│       ├── path.ts            # Path validation (prevents traversal)
│       ├── tscn.ts            # .tscn parser and serializer
│       └── project_godot.ts   # project.godot reader
└── scripts/
    ├── setup.js               # Interactive setup wizard
    └── godot_operations.gd    # Bundled GDScript for runtime ops

Compatibilidad

• Godot 4.x (objetivo principal — probado en 4.2, 4.3, 4.4)

• Godot 3.x — las herramientas básicas funcionan; se aplican diferencias en el formato de escena

• Protocolo MCP — especificación 2024-11-05

• Node.js — 18+

Seguridad

• Todas las rutas de archivo se validan para permanecer dentro del directorio del proyecto (sin recorrido de rutas)

• launch_editor y run_project solo inician procesos con argumentos seguros y predefinidos

• Usa READ_ONLY_MODE=true en entornos no confiables

• El servidor nunca ejecuta comandos de shell arbitrarios, solo el binario de Godot

Licencia

MIT