Docs · Best Practices · Godot

Effective AI requests in Godot

Nodes, scenes, and resources — driven through both C# and GDScript with a reflection escape hatch.

Last updated: 2026-06-17 View as Markdown

What it is

Godot-MCP (branded "AI Game Developer — Godot") is a C# (.NET / mono) editor addon for the Godot Editor. It exposes Godot Editor operations — creating and editing the scene tree (nodes), opening/saving .tscn scenes, finding and mutating .tres/.res resources, reading/creating/updating both C# (.cs) and GDScript (.gd) scripts and attaching them to nodes, capturing screenshots, and a C# reflection escape hatch — as AI Tools, so an MCP-compatible AI client can drive the Godot Editor through natural language.
Godot 4.3+ (.NET build), a C# / .NET project. Addon: godot_mcp. Install via godot-cli (npm) or the Asset Library.

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.

FamilyToolsPurpose
Editor3Query 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.
Script8Read, create, update, delete .cs or .gd scripts; attach a script to a node; validate GDScript; build the C# project; run C# in the editor.
Screenshot3Viewport, camera, isolated-node renders.
Console2In a running game: read (with filtering) and clear the collected logs. In the editor, use the RQL console source.
Reflection2In a running game: find and call any C# method across loaded assemblies (via ReflectorNet). In the editor, use RQL calls.
Runtime Errors2Read and clear errors captured inside the running game — off by default, opt in with builder.WithRuntimeErrorCapture().
Ping1Lightweight 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.

  1. Add a Node3D scene with a Camera3D and a MeshInstance3D cube, then save it as `Main.tscn`.
  2. Add a `MeshInstance3D` cube under the `World` node, move it to the origin, and name it `Hero`.
  3. Create a new `StandardMaterial3D` resource for the floor, then set its albedo color to grey.
  4. Create 3 cubes in a circle with radius 2.
  5. Run the game, then take a screenshot of the viewport.
  6. Create a `HealthBar.cs` script with a public float `Health`, add a `_Ready` method, then attach it to the `Player` node.
  7. 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.

  1. Open the Godot editor, open the AI Game Developer dock, choose Cloud, click Authorize, and wait for the status to go green.
  2. Ask your client: "Ping the Godot addon to check the connection."
  3. Ask: "Add a `MeshInstance3D` cube under the root node, name it `Hero`, then take a viewport screenshot."
  4. Confirm the node appears in the scene tree and read back the screenshot.
  5. 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.

  1. Ping the Godot addon to check the connection. (ping)
  2. List every tool you can call, grouped by family.
  3. Show me the nodes in the open scene. (rql-query: nodes | select name class path)
  4. Can you write both C# and GDScript here? (yes — the Script family handles .cs and .gd)
  5. What resources are in the project? (rql-query on the files source)
  6. 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.

Keep going