Godot MCP Pro

168 herramientas impulsadas por IA para el editor de Godot 4: conecta tu asistente de IA (Claude, Cursor, Cline, Copilot) a Godot y crea juegos con lenguaje natural.

Cómo funciona

Conecta tu asistente de IA a Godot en menos de 5 minutos.

1. Instala el plugin

Copia addons/godot_mcp/ en tu proyecto de Godot. Habilítalo en Proyecto > Ajustes del proyecto > Plugins. El plugin inicia automáticamente un servidor WebSocket dentro del editor.

2. Construye el servidor MCP

cd server
npm install && npm run build

Esto compila el servidor MCP en TypeScript que conecta tu cliente de IA con el plugin de Godot.

3. Empieza a construir con IA

Añade el servidor a la configuración MCP de tu cliente de IA. Abre Godot y tu asistente de IA tendrá acceso en tiempo real a 168 herramientas: crear escenas, editar scripts, simular entradas y analizar tu juego en ejecución.

Configuración del cliente MCP

Claude Code / Claude Desktop

Añade a .claude/mcp.json:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

VS Code / Cursor

Añade a .vscode/mcp.json:

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["./server/dist/index.js"]
    }
  }
}

Cualquier cliente MCP stdio

node server/dist/index.js

El servidor se comunica a través de stdio (stdin/stdout) utilizando el protocolo MCP.

Configuración automatizada (recomendado)

cd server
npm run run

Esto hará automáticamente lo siguiente:

Construir el servidor MCP
Detectar project.godot en carpetas principales (o GODOT_PROJECT_PATH)
Sincronizar el addon a addons/godot_mcp
Habilitar el plugin en project.godot
Crear archivos de configuración MCP
Sincronizar archivos de contexto de IA

Categorías de herramientas

#	Categoría	Herramientas	Aspectos destacados
1	Proyecto	7	Lectura/escritura de ajustes, conversión de UID
2	Escena	9	Crear, abrir, reproducir, detener, instanciar, guardar
3	Nodo	14	Añadir/eliminar/renombrar/mover con UndoRedo, señales, grupos
4	Script	8	CRUD, adjuntar, validar, buscar con números de línea
5	Editor	10	Capturas de pantalla, ejecutar GDScript, registro de errores, recargar
6	Entrada	7	Teclado, ratón, simulación de acciones, secuencias
7	Runtime	19	Inspección de juego, captura de fotogramas, grabación/reproducción, UI
8	Animación	6	CRUD, pistas, fotogramas clave
9	AnimationTree	8	Máquina de estados, transiciones, árbol de mezcla
10	TileMap	6	Operaciones de celdas (TileMapLayer para Godot 4.3+)
11	Escena 3D	6	Primitivas de malla, importación .glb, preajustes de iluminación, PBR
12	Física	6	Colisión 2D/3D automática, raycasts, capas
13	Partículas	5	Partículas GPU + preajustes de fuego/humo/lluvia/nieve/chispas
14	Navegación	6	Región, agente, bake, búsqueda de rutas
15	Audio	6	Reproductor (automático 2D/3D), cadena de efectos de bus
16	Tema/UI	6	StyleBoxFlat, anulaciones de color/constante/fuente
17	Shader	6	Plantillas (canvas_item, spatial, particles, sky)
18	Recurso	6	CRUD de .tres, gestión de carga automática
19	Lote	8	Buscar por tipo, configuración masiva, análisis de dependencias
20	Pruebas	6	Escenarios automatizados, aserciones, pruebas de estrés
21	Análisis	4	Complejidad de escena, flujo de señales, recursos no utilizados
22	Perfilado	2	FPS, memoria, física, monitores de renderizado
23	Exportación	3	Listado de preajustes, comandos de compilación
	Total	168	+ 4 herramientas de conexión principales

Características clave

🧠 Análisis inteligente de tipos

No es necesario construir objetos complejos manualmente. Los valores de las propiedades se convierten automáticamente:

"Vector2(100, 200)"  → Vector2(100, 200)
"Color(1, 0, 0)"    → Color(1, 0, 0)
"#ff0000"            → Color(1, 0, 0)
"Color.RED"          → Color(1, 0, 0)
"true"               → true
"42"                 → 42

♻️ Deshacer/Rehacer en todas las mutaciones

Cada add_node, delete_node, update_property, rename_node y move_node pasa por el sistema UndoRedo de Godot. Tus usuarios pueden hacer Ctrl+Z en cualquier acción de la IA.

🎯 Detección automática 2D/3D

Los cuerpos físicos, formas de colisión, reproductores de audio, partículas y nodos de navegación detectan automáticamente si el padre es 2D o 3D; el tipo correcto se crea siempre.

🔥 Preajustes integrados

Iluminación: sol, interior, dramática, foco
Partículas: fuego, humo, lluvia, nieve, chispas
Shaders: plantillas canvas_item, spatial, particles, sky
Efectos de audio: reverberación, retardo, compresor, ecualizador, distorsión, coro, phaser

Ejemplo rápido

AI: godot_connect
AI: create_scene path="res://scenes/level.tscn" rootType="Node2D"
AI: add_node type="CharacterBody2D" name="Player" parentPath="."
AI: add_node type="Sprite2D" name="Sprite" parentPath="Player"
AI: update_property path="Player/Sprite" property="texture" value="res://icon.svg"
AI: setup_collision path="Player" shapeType="rectangle" size="Vector2(32, 32)"
AI: create_script path="res://scripts/player.gd" content="extends CharacterBody2D..."
AI: attach_script nodePath="Player" scriptPath="res://scripts/player.gd"
AI: save_scene
AI: play_scene
AI: simulate_key key="Space"
AI: get_game_screenshot
AI: stop_scene

Arquitectura

server/src/
├── index.ts           TypeScript MCP server (stdio transport)
├── toolCatalog.ts     168 tool definitions with input schemas
└── godotBridge.ts     WebSocket client → Godot editor

addons/godot_mcp/
├── plugin.gd          Plugin entry point
├── websocket_server.gd Local WebSocket server (port 6505)
├── command_router.gd  Loads 20 handler modules, dispatches commands
└── commands/
    ├── base_commands.gd        Shared utilities (type parser, undo, I/O)
    ├── type_parser.gd          Smart string→Godot type conversion
    ├── undo_helper.gd          UndoRedo wrapper
    ├── core_commands.gd        Project, scene, node, script, editor (47 handlers)
    ├── editor_commands.gd      Screenshots, execute script (4)
    ├── input_commands.gd       Input simulation (7)
    ├── runtime_commands.gd     Game inspection & UI (15)
    ├── animation_commands.gd   Animation CRUD (6)
    ├── animation_tree_commands.gd  State machine & blend tree (8)
    ├── tilemap_commands.gd     Tile operations (6)
    ├── scene3d_commands.gd     3D scene building (6)
    ├── physics_commands.gd     Physics & collision (6)
    ├── particles_commands.gd   GPU particles + presets (5)
    ├── navigation_commands.gd  Nav regions & pathfinding (6)
    ├── audio_commands.gd       Audio players & bus effects (6)
    ├── theme_commands.gd       Theme & UI styling (6)
    ├── shader_commands.gd      Shader management (4)
    ├── resource_commands.gd    Resource & autoload (6)
    ├── batch_commands.gd       Batch operations (8)
    ├── testing_commands.gd     Testing & QA (5)
    ├── analysis_commands.gd    Code analysis (4)
    ├── profiling_commands.gd   Performance profiling (2)
    └── export_commands.gd      Export management (3)

Protocolo del puente

JSON-RPC 2.0 sobre WebSocket (ws://127.0.0.1:6505):

→ { "jsonrpc": "2.0", "id": 1, "method": "add_node", "params": { "type": "Sprite2D", "name": "Player" } }
← { "jsonrpc": "2.0", "id": 1, "result": { "tool": "add_node", "data": { "path": "/root/Main/Player" } } }

Anular URL del puente: GODOT_WS_URL=ws://127.0.0.1:6505 node server/dist/index.js

Requisitos

Godot 4.2+ (4.3+ recomendado para TileMapLayer)
Node.js 18+
Cualquier cliente de IA compatible con MCP

Archivos de contexto del agente de IA

Cuando se despliegan en un proyecto de Godot, estos archivos de contexto ayudan a los asistentes de IA a entender las herramientas disponibles:

Archivo	Propósito	Utilizado por
`addons/godot_mcp/skills.md`	Referencia completa de 168 herramientas con flujos de trabajo	Todos los agentes de IA
`AGENTS.md`	Resumen de arquitectura + capacidades	Codex, Gemini, agentes
`CLAUDE.md`	Referencia rápida + comandos de compilación	Claude Code
`.github/copilot-instructions.md`	Instrucciones específicas para Copilot	GitHub Copilot

Godot MCP Bridge