Godot MCP Server

godot-mcp permite a los clientes MCP inspeccionar, validar, probar, exportar y consultar proyectos de Godot. Admite comandos headless de Godot y, opcionalmente, el estado en vivo de un editor de Godot abierto.

Requisitos

• Node.js 18 o más reciente

• Godot 4.1 o más reciente, instalado localmente

• Un proyecto de Godot que contenga project.godot

Las herramientas de editor en vivo requieren además el complemento MCP Bridge descrito a continuación. Las herramientas restantes se ejecutan de forma headless.

Related MCP server: godot-ai-mcp

Instalación

Desde una copia local

npm install
npm run build

Desde npm (después de la publicación)

npx -y @zbrkic/godot-mcp --project /path/to/godot-project --godot /path/to/godot

Configurar un cliente MCP

Proporcione siempre la ruta del proyecto. Los clientes de escritorio MCP suelen iniciar servidores en su propio directorio de trabajo, por lo que la detección automática de proyectos por sí sola no es fiable.

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@zbrkic/godot-mcp"],
      "env": {
        "GODOT_PROJECT_PATH": "C:/Source/my-game",
        "GODOT_PATH": "C:/Program Files/Godot/Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

Las opciones equivalentes de línea de comandos son:

godot-mcp --project /path/to/godot-project --godot /path/to/godot

GODOT_PATH/--godot es opcional solo cuando el ejecutable godot ya está en PATH. En Windows, se prefiere un ejecutable _console.exe.

Habilitar herramientas de editor en vivo

1. Copie godot-plugin/addons/mcp_bridge a <your-project>/addons/mcp_bridge.

2. En Godot, abra Proyecto > Configuración del proyecto > Plugins y habilite MCP Bridge.

3. Mantenga abierto el editor de Godot mientras usa las herramientas en vivo.

El puente escucha en 127.0.0.1:7000 de forma predeterminada. Establezca mcp/plugin/port en project.godot para anularlo; el servidor lee esa configuración del proyecto configurado anteriormente. Excluya addons/mcp_bridge/* de los ajustes preestablecidos de exportación de producción.

Herramientas

• Proyecto y exportación: get_project_settings, list_export_presets, export_project

• Pruebas y validación: run_tests, validate_scene, validate_script, run_scene, format_gdscript

• Escenas y recursos: inspect_scene_tree, find_nodes, get_node_properties, get_node_connections, list_resources, get_resource_dependencies, resolve_path, get_resource_info

• Documentación: verify_api, get_help

• Editor en vivo: get_editor_selection, get_open_scenes

La mayoría de las herramientas devuelven un resultado JSON estructurado con success, data, errors, warnings y metadatos de tiempo.

Desarrollo y verificación

npm test              # TypeScript build plus MCP handshake and parser tests
npm run test:godot    # GDScript syntax checks; requires GODOT_PATH or godot on PATH
npm pack --dry-run    # Inspect the files that would be published

GitHub Actions ejecuta tanto las pruebas de Node/MCP como las comprobaciones del complemento de Godot en pushes y pull requests.

Lista de verificación de lanzamiento

1. Actualice la versión en package.json.

2. Ejecute npm test, npm run test:godot y npm pack --dry-run.

3. Publique con npm publish y cree una versión de GitHub correspondiente.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.