Esta página se tradujo automáticamente del inglés. Lee el original en inglés.

Herramientas

Herramientas MCP de Godot para agentes de IA: consultas RQL de nodos, escenas y recursos, scripts de C# y GDScript, capturas y herramientas en juego.

Actualizado el 4 de noviembre de 2026 Ver como Markdown

Godot MCP incluye 24 herramientas integradas en 9 familias. La mayor parte del trabajo en el editor pasa por tres herramientas RQL, así que el agente usa un único lenguaje de consultas para nodos, escenas, recursos, archivos y el estado del editor en lugar de decenas de herramientas separadas. Esta página explica cada familia y cuándo la usa el agente. La lista con búsqueda, con parámetros y prompts de ejemplo, es el catálogo de herramientas de Godot.

Familias de herramientas

FamiliaHerramientasPara qué sirve
rqlrql-query, rql-mutate, rql-schemaLeer y modificar el editor en vivo: nodos, propiedades de Godot, escenas, recursos, archivos, ajustes del proyecto, mapa de entrada, autoloads, grupos, señales y estado del editor.
scriptscript-read, script-create, script-update, script-delete, script-attach-to-node, script-validate, script-build, script-executeArchivos de C# y GDScript, adjuntar scripts, validar GDScript, compilar el proyecto de C# y ejecutar C# en el editor.
screenshotscreenshot-viewport, screenshot-camera, screenshot-isolatedImágenes PNG del viewport del editor, de una cámara o de un nodo renderizado por separado.
consoleconsole-get-logs, console-clear-logsRegistros de un juego en ejecución. En el editor, la fuente console de RQL.
reflectionreflection-method-find, reflection-method-callBuscar y llamar métodos de C# en un juego en ejecución. En el editor, call de RQL.
runtime-errorsruntime-errors-get, runtime-errors-clearErrores producidos dentro de un juego en ejecución. Desactivado por defecto.
pingpingSonda de disponibilidad. Una herramienta del sistema, no se muestra a los agentes.
skillsgodot-skill-create, godot-skill-generateEscribir un archivo de herramienta nuevo, regenerar los archivos de skills. Herramientas del sistema.
sessionsession-closeGuardar y cerrar un editor que inició godot-cli. Herramienta del sistema.

Se accede a las herramientas del sistema por la ruta /api/system-tools/ del servidor (por ejemplo, con godot-cli run-system-tool ping) y no se listan a los agentes de IA. Las familias console, reflection y runtime-errors sirven a un juego en ejecución que hayas conectado tú mismo; consulta Herramientas personalizadas.

RQL: un único lenguaje de consultas para el editor

RQL (Reflection Query Language) es la capa de datos de las herramientas del editor. Una consulta parte de una fuente, la filtra y le da forma con etapas separadas por |, y en rql-mutate termina con set o call. Algunos ejemplos que el agente podría enviar:

nodes | where class == "OmniLight3D" | select name props["light_energy"]
nodes | where name starts-with "Enemy" | set Visible = false
root | call AddChild("Node3D", "Props")
project | call AddInputAction("jump", ["Key:Space"])
files | sort size desc | first 5 | select path size importedSize
editor | call SaveScene()
  • rql-query es de solo lectura y devuelve filas compactas.
  • rql-mutate modifica cosas. Cada destino y cada valor se comprueba primero, así que una consulta fallida no cambia nada. dry_run previsualiza el cambio. Cada llamada es un paso de deshacer (Ctrl+Z en el editor).
  • rql-schema lista las fuentes, funciones y clases de nodo de la escena editada, o los miembros, métodos y propiedades de Godot de un tipo. Con un nombre de extensión, imprime la guía de esa extensión.

Las fuentes incluyen nodes, root, selection, scenes, files, folders, classes, console, editor, project, settings, inputActions, autoloads, groups, layers y tools. Se puede acceder a las propiedades de Godot como miembros de C# (Position, Visible) o por su nombre de Godot en props["snake_name"], que incluye las variables de GDScript. RQL también maneja señales, grupos, TileSets, Themes, parámetros de ShaderMaterial y MeshLibraries.

Las llamadas del editor cubren el trabajo con escenas y archivos: NewScene, OpenScene, SaveScene, SaveAllScenes, ReloadScene, CreateResource, MoveResource, DeleteResource, CreateFolder, DeleteFolder, Reimport, Undo, Redo, PlayScene y StopScene. La fuente gameLog lee lo que imprimió un juego iniciado desde el editor.

Las ediciones de escena marcan la escena como no guardada, igual que tus propias ediciones. Los archivos de recursos editados y project.godot se guardan inmediatamente.

Scripts: C# y GDScript

  • script-read, script-create, script-update y script-delete trabajan sobre archivos .cs y .gd.
  • script-attach-to-node adjunta un script a un nodo.
  • script-validate devuelve diagnósticos de análisis y compilación de los archivos GDScript; sin una ruta, comprueba todos los archivos .gd bajo res://.
  • script-build ejecuta dotnet build (Debug) para que se carguen los scripts de C# nuevos. Después, Godot recarga el ensamblado de C# y el addon se reconecta, y el resultado de la compilación (advertencias o errores) llega tras la recarga.
  • script-execute compila y ejecuta C# en el editor con Roslyn. Escribe instrucciones simples; la última expresión es el resultado. Devuelve el valor y lo que imprimió el código. Los fragmentos agotan el tiempo de espera tras 30 segundos por defecto (como máximo 4 minutos), y un bucle infinito devuelve un error de tiempo de espera en lugar de congelar el editor.

También puedes llamar a script-execute desde una terminal:

godot-cli exec 'EditorInterface.Singleton.GetEditedSceneRoot()?.Name' --path ./MyGodotProject

Capturas de pantalla

Las herramientas de captura de pantalla devuelven imágenes PNG que el modelo puede inspeccionar: screenshot-viewport captura el viewport del editor, screenshot-camera renderiza desde un nodo de cámara y screenshot-isolated renderiza un nodo por sí solo desde un ángulo elegido. Pide una captura de pantalla después de cambios visuales para que el agente pueda comprobar su propio trabajo.

Herramientas en el juego

console-*, reflection-* y runtime-errors-* se ejecutan dentro de tu juego, no en el editor. Un juego no expone nada hasta que tu código lo habilita y se conecta; runtime-errors-get además necesita WithRuntimeErrorCapture(). Captura errores de tiempo de ejecución de GDScript, push_error y push_warning, errores de shaders (Godot 4.5 y posteriores) y excepciones de C# no controladas, de modo que un agente puede ejecutar el juego y ver qué falló realmente. Configuración: Herramientas personalizadas.

Elegir qué herramientas ve el agente

Cada herramienta tiene un interruptor Visible en el dock (MCP features, Tools, Open) y en godot-cli configure. Ocultar una herramienta la elimina de la lista de herramientas del agente, lo que ahorra contexto, pero no la bloquea. Consulta Configuración.

Más herramientas

  • Extensiones enseñan a RQL sobre AnimationPlayer, CSG, GridMap, navegación, partículas, TileMapLayer y los addons Beehave, Dialogic, Phantom Camera y Terrain3D.
  • Herramientas personalizadas muestra cómo escribir tus propias herramientas en C#.
  • Buenas prácticas para Godot contiene patrones de prompts que usan bien estas herramientas.