Effective AI requests in Godot
Nodes, scenes, and resources — driven through both C# and GDScript with a reflection escape hatch.
What it is
Tool-family map
You never call tool ids by hand — but knowing the families helps you frame requests and ask the agent "what can you do with X?". The full searchable catalog lives on the Godot tools page.
| Family | Tools | Purpose |
|---|---|---|
| Editor | 3 | Query and change nodes, scenes, resources, files and editor state with RQL (Reflection Query Language): rql-query, rql-mutate, rql-schema. All-or-nothing and undoable. |
| Script | 8 | Read, create, update, delete .cs or .gd scripts; attach a script to a node; validate GDScript; build the C# project; run C# in the editor. |
| Screenshot | 3 | Viewport, camera, isolated-node renders. |
| Console | 2 | In a running game: read (with filtering) and clear the collected logs. In the editor, use the RQL console source. |
| Reflection | 2 | In a running game: find and call any C# method across loaded assemblies (via ReflectorNet). In the editor, use RQL calls. |
| Runtime Errors | 2 | Read and clear errors captured inside the running game — off by default, opt in with builder.WithRuntimeErrorCapture(). |
| Ping | 1 | Lightweight readiness probe — echoes a message / returns pong. |
Godot-MCP’s core addon exposes 21 tools across the 7 families listed here. On top of that, 10 Godot-AI-* extension packages add 26 RQL capabilities (no extra MCP tools: each is an RQL module) — Animation, CSG, GridMap, Navigation, Particles, and Tilemap, plus addon integrations (Beehave, Dialogic, PhantomCamera, Terrain3D). See /docs/extensions/godot.
Example prompts
Copy-pasteable first requests. Start with one, verify in the editor, then build up.
Add a Node3D scene with a Camera3D and a MeshInstance3D cube, then save it as `Main.tscn`.Add a `MeshInstance3D` cube under the `World` node, move it to the origin, and name it `Hero`.Create a new `StandardMaterial3D` resource for the floor, then set its albedo color to grey.Create 3 cubes in a circle with radius 2.Run the game, then take a screenshot of the viewport.Create a `HealthBar.cs` script with a public float `Health`, add a `_Ready` method, then attach it to the `Player` node.Create a `Patrol.gd` GDScript with a `_process(delta)` method, then attach it to the `Enemy` node.
Your first request
A tiny, verifiable loop to confirm everything works.
- Open the Godot editor, open the AI Game Developer dock, choose Cloud, click Authorize, and wait for the status to go green.
- Ask your client: "Ping the Godot addon to check the connection."
- Ask: "Add a `MeshInstance3D` cube under the root node, name it `Hero`, then take a viewport screenshot."
- Confirm the node appears in the scene tree and read back the screenshot.
- Build up — "Create a HealthBar.cs script with a public float Health and attach it to the Player node."
Discover what the agent can do
Discovery is conversational — ask the agent these in order to map its capabilities.
- Ping the Godot addon to check the connection. (ping)
- List every tool you can call, grouped by family.
- Show me the nodes in the open scene. (rql-query: nodes | select name class path)
- Can you write both C# and GDScript here? (yes — the Script family handles .cs and .gd)
- What resources are in the project? (rql-query on the files source)
- Pick one family and ask for a tiny concrete action plus a viewport screenshot.
Common pitfalls
- C# project + two NuGet pins are mandatory. Godot compiles every .cs under the project into one assembly, so your .csproj must declare the same PackageReferences the addon needs: com.IvanMurzak.ReflectorNet and com.IvanMurzak.McpPlugin. godot-cli install-plugin adds them for you; on a manual install, add them yourself.
- If you see FileNotFoundException: Could not load ... ReflectorNet, the pins are missing or the build is stale — add the pins and rebuild. Healthy boot logs "[Godot-MCP] plugin loaded".
- Play runs in a separate process, so screenshots of "the game" differ from editor-viewport captures.
- Resource-typed properties can be awkward — some (e.g. assigning a Mesh) cannot be set directly with an RQL set. Instead instance a .tscn sub-scene with the RQL call InstantiateScene. Property paths are PascalCase.