Godot MCP Server

Un completo servidor FastMCP para el desarrollo de juegos con Godot 4.x. Proporciona herramientas para flujos de trabajo asistidos por IA: gestión de proyectos, operaciones de archivos, descubrimiento de activos, desarrollo en GDScript y ejecución opcional de Godot.

Contribuciones · Seguridad

Modelo de seguridad: Todos los proyectos de Godot, la escritura de archivos y las descargas de Asset Library están restringidos a un único directorio del espacio de trabajo en tu máquina (por defecto ~/godot-games). El servidor rechaza rutas fuera de ese árbol. Consulta Configuración del espacio de trabajo.

Ejecución de código: godot_run_game y godot_execute_script requieren GODOT_MCP_ALLOW_GODOT_EXEC en el entorno del servidor. Los archivos de configuración MCP incluidos la establecen en 1 para que estas herramientas funcionen tras copiar y pegar. Ejecutar python godot_mcp_server.py sin esa variable de entorno deja la ejecución desactivada hasta que la exportes. Para blindar una instalación en el IDE, elimina la variable o ajústala a 0. Consulta Ejecución de Godot (entorno).

Transporte HTTP: Enlazar a 0.0.0.0 o :: expone el servidor MCP en todas las interfaces de red; prefiere 127.0.0.1 a menos que uses un firewall o VPN.

Enlaces simbólicos: GODOT_MCP_ROOT se resuelve siguiendo los enlaces simbólicos; apúntalo a un directorio real que controles.

Características

Gestión de proyectos

• Detectar automáticamente proyectos de Godot (project.godot); listar todos los proyectos dentro del espacio de trabajo (godot_list_projects)

• Crear nuevos proyectos dentro del espacio de trabajo (godot_create_project)

• Analizar los ajustes y la configuración del proyecto; listar los autoloads y el estado de los plugins del editor (solo lectura para plugins)

• Refrescar la caché de proyectos tras los cambios

Operaciones de archivos

• Leer/escribir escenas (.tscn), scripts (.gd), recursos (.tres)

• Crear nuevos scripts, escenas y recursos a partir de plantillas

• Editar archivos existentes con reemplazo de contenido

• Validar la sintaxis de escenas y scripts

Generación de código

• Controladores de movimiento CharacterBody2D/3D

• Patrones de máquina de estados

• Recursos personalizados

• Scripts de nodo con señales/exportaciones

Gestión de activos

• Descubrir activos por extensión, patrón o glob

• Encontrar activos no utilizados

• Buscar contenido en archivos con regex

• Buscar y descargar desde Godot Asset Library

• Explorar repositorios de Godot en GitHub

Integración en tiempo de ejecución

• Encontrar el ejecutable de Godot

• Comprobar la versión de Godot

• Ejecutar el juego en modo headless

• Ejecutar código GDScript

• Leer los registros de Godot

• Configuración del observador de archivos

Related MCP server: Godot MCP

Instalación

# From PyPI-style editable install (recommended for contributors)
pip install -e .

# Or minimal deps only
pip install -r requirements.txt

Punto de entrada de consola (después de pip install -e .): godot-mcp-server (igual que python godot_mcp_server.py).

Configuración del espacio de trabajo (obligatorio)

El servidor MCP solo opera sobre proyectos de Godot que se encuentren bajo una única carpeta raíz. Esto evita que los asistentes lean o escriban rutas arbitrarias en tu sistema.

1. Crea la carpeta predeterminada (una vez por máquina):

mkdir -p ~/godot-games

2. Coloca todos los juegos de Godot allí — cada juego es su propia subcarpeta que contiene project.godot, por ejemplo:

~/godot-games/
  my-platformer/     ← open this folder in your editor
    project.godot
    ...
  another-game/
    project.godot

3. Abre tu espacio de trabajo del IDE dentro de ~/godot-games/.../your-game (o una carpeta superior bajo ~/godot-games) para que el proceso MCP pueda descubrir project.godot desde el directorio de trabajo actual.

4. Ubicación personalizada: establece una ruta absoluta antes de iniciar el servidor:

export GODOT_MCP_ROOT="/path/to/your/godot-games"
python godot_mcp_server.py

En Cursor / Claude / otras configuraciones MCP, añade env:

"env": {
  "GODOT_MCP_ROOT": "/path/to/your/godot-games"
}

Si no se establece, el valor predeterminado es $HOME/godot-games. El servidor crea ese directorio al iniciarse si no existe.

5. Inspecciona en tiempo de ejecución: llama a la herramienta godot_get_workspace o lee el recurso project://workspace para ver la ruta activa del espacio de trabajo.

Si las herramientas informan de que no se encontró ningún proyecto, tu cwd probablemente esté fuera del espacio de trabajo, o project_path apunta fuera de GODOT_MCP_ROOT.

Ejecución de Godot (entorno)

Ejecutar el juego o ejecutar GDScript ejecuta código como tu usuario (igual que iniciar Godot desde una terminal). El servidor solo habilita godot_run_game / godot_execute_script cuando GODOT_MCP_ALLOW_GODOT_EXEC tiene un valor «activado» aceptado.

Configuraciones incluidas (sí por defecto): cada JSON de ejemplo en este repositorio (mcp_config.json, mcp_config.cursor.json, etc.) incluye:

"env": {
  "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
}

Por lo tanto, si copias uno de ellos en tu IDE, la ejecución está permitida sin pasos adicionales. Combina otras claves (p. ej. GODOT_MCP_ROOT) en el mismo objeto env.

CLI sin configuración MCP: ejecutar python godot_mcp_server.py no establece esta variable; las herramientas de ejecución permanecen bloqueadas hasta que ejecutes export GODOT_MCP_ALLOW_GODOT_EXEC=1 (o uses un script envoltorio).

Configuraciones más estrictas: elimina GODOT_MCP_ALLOW_GODOT_EXEC de env, o ajústala a 0 / false / no / off, y reinicia el cliente MCP.

Valores «activado» aceptados: 1, true, yes, on (no distingue mayúsculas). Llama a godot_get_workspace y comprueba godot_exec_allowed para confirmarlo.

Uso

CLI (stdio - para Claude Code/Cursor)

python godot_mcp_server.py

Servidor HTTP

python godot_mcp_server.py --transport http --port 8765

Configuración

Establece GODOT_MCP_ROOT en el env del servidor MCP si no usas ~/godot-games por defecto. Consulta Configuración del espacio de trabajo. Los fragmentos incluidos a continuación incluyen GODOT_MCP_ALLOW_GODOT_EXEC; consulta Ejecución de Godot (entorno).

Ruta al servidor: los ejemplos usan "args": ["godot_mcp_server.py"] asumiendo que el proceso MCP se ejecuta con su directorio de trabajo en la carpeta que contiene el script (p. ej. has clonado este repositorio). Si el servidor no se inicia, reemplázalo con la ruta absoluta a godot_mcp_server.py en tu máquina.

Instalación en tu editor

Expande una sección y pega el JSON en el archivo que espera tu herramienta. El mismo bloque de servidor godot está en el repositorio como mcp_config.*.json para copiar y pegar.

macOS / Linux (configuración de proyecto o usuario) — Configuración → MCP → Añadir nuevo servidor MCP global o crea .cursor/mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Windows — si python no está en el PATH del host MCP, usa el lanzador o la ruta completa a python.exe, y prefiere una ruta absoluta en args:

{
  "mcpServers": {
    "godot": {
      "command": "cmd",
      "args": ["/c", "python", "C:\\path\\to\\godot-mcp-server\\godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Combina GODOT_MCP_ROOT en env si no usas ~/godot-games (consulta Configuración del espacio de trabajo).

Usa la configuración de MCP / agente que proporciona tu versión de VS Code (a menudo Configuración → MCP o un .vscode/mcp.json de proyecto, según la versión y las extensiones). Pega la misma estructura que en Cursor:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Usa una ruta absoluta en args si la carpeta del espacio de trabajo no es la raíz del repositorio.

Edita el archivo de configuración de la aplicación:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["/absolute/path/to/godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      }
    }
  }
}

Reinicia Claude Desktop después de guardar.

Añádelo a ~/.claude/settings.json (o usa claude mcp add si tu CLI lo admite — consulta claude mcp --help):

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server"
    }
  }
}

macOS / Linux: edita ~/.codeium/windsurf/mcp_config.json, o usa CMD+SHIFT+P → “Windsurf: Configurar servidores MCP”.

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development - project, scenes, scripts, assets, runtime"
    }
  }
}

Pega en la configuración MCP de Roo (de proyecto o global), con la misma forma JSON que arriba. Copia en el repositorio: roo_code_mcp.json.

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game dev - project, scenes, scripts, assets, runtime"
    }
  }
}

Configuración stdio mínima — igual que mcp_config.json en este repositorio:

{
  "mcpServers": {
    "godot": {
      "command": "python3",
      "args": ["godot_mcp_server.py"],
      "env": {
        "GODOT_MCP_ALLOW_GODOT_EXEC": "1"
      },
      "description": "Godot 4.x game development server - file ops, asset management, runtime integration"
    }
  }
}

Límites (DoS / abuso)

• Búsqueda con regex (godot_search_content): longitud de patrón limitada; lista de coincidencias limitada; los archivos de más de 2 MiB se omiten. Un regex malicioso aún puede resultar costoso: mantén los patrones simples.

• Descarga de zip de activos: se aplican el tamaño máximo de descarga, el tamaño descomprimido por archivo, el tamaño descomprimido total y el número de archivos antes de la extracción (consulta las constantes cerca del inicio de godot_mcp_server.py).

• IDs de Asset Library: asset_id para godot_get_asset_info / godot_download_asset debe contener solo dígitos numéricos.

Modo HTTP (remoto)

Usa loopback a menos que sepas lo que haces:

python godot_mcp_server.py --transport http --host 127.0.0.1 --port 8765

Enlazar a todas las interfaces (--host 0.0.0.0) registra una advertencia y expone MCP a tu LAN sin autenticación en este servidor.

Luego usa serverUrl en lugar de command:

{
  "mcpServers": {
    "godot": {
      "serverUrl": "http://localhost:8765/mcp"
    }
  }
}

Ejecuta un solo transporte para el mismo proyecto (stdio o HTTP), no ambos a la vez, para evitar sesiones MCP conflictivas.

Referencia de herramientas

40 herramientas MCP están registradas en godot_mcp_server.py (busca @mcp.tool). Resumen:

Complementos del editor: este servidor no escribe [editor_plugins] en project.godot (evita conflictos con un editor abierto). Instala los complementos mediante las herramientas anteriores; el usuario habilita los complementos en Configuración del proyecto → Plugins en Godot; usa godot_list_editor_plugins para verificarlo.

Recursos

Ejemplos

Crear un jugador de plataformas

# Using template
create_code_template("character_body_2d", "Player")

Buscar activos

# All PNG files
find_assets([".png", ".jpg"])

# Unused assets
find_unused_files()

Buscar en Asset Library

search_assetlib("platformer")
# => [{title: "PlatformerController2D", ...}]

get_asset_info("1062")
# => {title, author, description, license, download_url}

Ejecutar el juego en modo headless

Requiere GODOT_MCP_ALLOW_GODOT_EXEC (incluido en las configuraciones JSON de MCP distribuidas).

run_game(headless=True, quit_after_seconds=30)

Requisitos

• Python 3.10+

• Dependencias: fastmcp, urllib3 (consulta pyproject.toml)

Desarrollo

pip install -e ".[dev]"
ruff check godot_mcp_server.py tests
pytest

La integración continua se ejecuta en Python 3.10–3.14 (consulta .github/workflows/ci.yml). Dependabot abre PRs semanales para pip y GitHub Actions.

Opcional: pip install pre-commit && pre-commit install utiliza .pre-commit-config.yaml.

Publicar en GitHub

1. Crea un repositorio vacío en GitHub (sin README/licencia si ya los tienes localmente), p. ej. godot-mcp-server.

2. Añade el remoto y sube los cambios:

cd /path/to/godot-mcp-server
git remote add origin https://github.com/YOUR_USER/godot-mcp-server.git
git push -u origin main

O con GitHub CLI: gh repo create godot-mcp-server --public --source=. --remote=origin --push

Después del primer push, la CI se ejecuta en cada push y PR. Reemplaza sterion66 en las URL de las insignias del README si usas otra cuenta u organización.

Licencia

MIT