Docs · Best Practices · Godot
Effective AI requests in Godot
Nodes, scenes, and resources — driven through both C# and GDScript with a reflection escape hatch.
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–4.5, a C# / .NET (mono) 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.
| Family | Tools | Purpose |
|---|---|---|
| Ping | 1 | Lightweight readiness probe — echoes a message / returns pong. |
| Node | 6 | Find, create (optionally instancing a .tscn), modify, set-parent, duplicate, delete nodes in the active scene tree. |
| Scene | 5 | Open, save, create, list-opened, get-data for .tscn scenes. |
| Resource | 6 | Find, get-data, modify, create, move, delete .tres/.res resources. |
| Filesystem | 2 | List the res:// tree (via the editor file index); reimport files. |
| Script | 5 | Read, create, update, delete .cs or .gd scripts; attach a script to a node. |
| Screenshot | 3 | Viewport, camera, isolated-node renders. |
| Editor | 4 | Application get/set state (run/stop the game); selection get/set. |
| Console | 2 | Read (with filtering) and clear the plugin’s collected editor logs. |
| Reflection | 2 | Find and call any C# method across loaded assemblies (via ReflectorNet). |
Godot-MCP’s core addon exposes 36 tools across the 10 families listed here. On top of that, 10 Godot-AI-* extension packages now add a further 58 tools — 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 the 10 families.
- Show me the node tree of the main scene. (scene-get-data)
- Can you write both C# and GDScript here? (yes — the Script family handles .cs and .gd)
- What resources are in the project? (resource-find)
- 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. The CLI install step only flips the enable flag.
- 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. editor-application-set-state Play/Stop launches the game 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 via node-modify. Instead instance a .tscn sub-scene via node-create with instanceScenePath. Property paths are PascalCase.