Godot MCP is an AI-powered game development assistant for the Godot Editor. Connect Claude, Cursor, Copilot, or any MCP-aware agent to Godot and let it inspect and drive your project — create nodes, edit scenes, manage resources and scripts, capture screenshots, and more.

Godot-MCP is the Godot counterpart of Unity-MCP: a C# editor addon that exposes Godot Editor operations as AI Tools and connects them to an MCP server through the same hosted cloud backend (ai-game.dev) that powers Unity-MCP — or your own self-hosted server. The MCP / reflection stack is not forked: it is shared with Unity-MCP and consumed from nuget.org as PackageReferences.

💬 Join our Discord Server — Ask questions, showcase your work, and connect with other developers!

• ✔️ AI agents — Use the best agents from Anthropic, OpenAI, Google, or any other provider with no vendor lock-in
• ✔️ 42 built-in Tools — A wide range of MCP Tools across 12 families for operating the Godot Editor
• ✔️ C# & GDScript — Read, create, and update both .cs and .gd scripts, and attach them to nodes
• ✔️ Scene & Node control — Build and edit the scene tree, open/save .tscn scenes, mutate .tres/.res resources
• ✔️ Visual feedback — Capture viewport, camera, and isolated-node screenshots the LLM can inspect
• ✔️ Reflection escape hatch — Find and call any C# method across loaded assemblies via ReflectorNet
• ✔️ Cloud or self-hosted — Connect to ai-game.dev out of the box, or point at your own server
• ✔️ Natural conversation — Chat with AI like you would with a human

Quick Start

Get up and running from a terminal using the godot-cli (the Godot analog of unity-mcp-cli) — no manual file copying or csproj editing required:

# 1. Install godot-cli
npm install -g godot-cli

# 2. (Optional) Scaffold a fresh Godot C# project — skip if you already have one
godot-cli create-project --dotnet ./MyGodotProject

# 3. Install the godot_mcp addon: downloads addons/godot_mcp/ from the matching
#    GitHub release, adds the required NuGet packages + the extension-catalog
#    EmbeddedResource to your .csproj, and enables the plugin in project.godot —
#    all idempotently
godot-cli install-plugin ./MyGodotProject

# 4. Sign in to the ai-game.dev cloud — OAuth 2.1 device login (opens a browser,
#    saves a machine-wide credential the editor plugin auto-adopts; no token to copy)
godot-cli login

# 5. Pick an AI agent (Claude Code, Cursor, Copilot, …) and write its MCP config —
#    pinned to THIS project's cloud route by default (pass --no-pin for the bare URL)
godot-cli setup-mcp claude-code ./MyGodotProject

# 6. Open the Godot editor — builds the C# assembly first (so the addon loads on
#    the very first open) then auto-connects with the right GODOT_MCP_* env vars
godot-cli open ./MyGodotProject

# 7. Wait until the plugin answers the readiness probe
godot-cli wait-for-ready ./MyGodotProject

That's it. Ask your AI "Create 3 cubes in a circle with radius 2" and watch it happen. ✨

Offline / dev install: install-plugin --source <path-to>/addons/godot_mcp copies the addon from a local directory instead of downloading it. Prefer the matching release version with install-plugin --version <x.y.z> if you need a specific addon build. The manual route (copy the addon + add the NuGet packages yourself) is still documented under Installation Steps 1–2 for the Asset Library / hand-managed flows.

See the full CLI documentation for every command, editor-resolution order, and connection env vars.

Contents

• Quick Start
• Tools Reference
• Requirements
• Installation
  • Step 1: Add the addon
    • Option A — Godot Asset Library (recommended)
    • Option B — GitHub Release zip
    • Option C — copy from source
  • Step 2: Add the NuGet packages
  • Step 3: Install an AI agent
• Connect
  • Cloud mode (default) — ai-game.dev
  • Custom mode — your own server
• Godot MCP Server setup
  • Local server — let the addon download & run it for you
  • Build & run the server manually (advanced)
• Customize Tools
• Runtime usage (in-game)
  • Capturing in-game runtime errors
  • Sample: a live game-state tool
  • Where the server URL and token come from
  • Security: opt-in only, default OFF
• How Godot MCP Architecture Works
• Building & contributing
• License

Tools Reference

Godot-MCP ships 42 built-in tools grouped into 12 families. Tool names mirror Unity-MCP where sensible (scene-*, node-*, …). Every tool returns a structured, ReflectorNet-serialized result (or a PNG image for screenshots). All editor tools are available immediately after the addon is enabled — no extra configuration required. The runtime-errors family is the exception: it surfaces errors from the running game and is OFF by default — opt in with builder.WithRuntimeErrorCapture() (see Capturing in-game runtime errors).

Family	Tools	What it does
ping	ping	Lightweight readiness probe — echoes a message back, or returns pong. Verifies the end-to-end MCP path (editor → SignalR → tool dispatch). System tool — reachable over the server's /api/system-tools/ HTTP surface, not advertised to AI agents in tools/list.
node	node-find, node-create, node-modify, node-set-parent, node-reorder, node-duplicate, node-delete	Inspect and edit the active scene tree (the Godot analog of Unity GameObjects), driving EditorInterface on the main thread. Child order — which is layout order in a VBoxContainer/HBoxContainer — is settable both on creation (node-create's index) and afterwards (node-reorder).
scene	scene-open, scene-save, scene-create, scene-list-opened, scene-get-data	Open, save, create, and inspect Godot scenes (res://*.tscn PackedScenes) in the editor.
resource	resource-find, resource-get-data, resource-modify, resource-create, resource-move, resource-delete	Find and mutate Godot resources (.tres/.res) through ResourceLoader/ResourceSaver/EditorFileSystem, keeping .import sidecars consistent.
filesystem	filesystem-list, filesystem-reimport	Browse and reimport the project's res:// tree via the editor EditorFileSystem index (file types + uids without loading resources).
script	script-read, script-create, script-update, script-delete, script-attach-to-node, script-validate	CRUD on C# (.cs) and GDScript (.gd) files, plus attaching a script to a node and validating GDScript.
screenshot	screenshot-viewport, screenshot-camera, screenshot-isolated	Capture the editor viewport, a specific camera, or an isolated node render, returned as a PNG image the LLM can inspect.
editor	editor-application-get-state, editor-application-set-state, editor-selection-get, editor-selection-set	Read/drive the editor run-and-play lifecycle (Godot launches the game in a separate process) and the current selection.
console	console-get-logs, console-clear-logs	Read and clear the plugin's editor log collector (GD.Print/GD.PushWarning/GD.PushError).
reflection	reflection-method-find, reflection-method-call	Find and call C# methods (static/instance, public/private) across every loaded assembly via ReflectorNet — the engine-agnostic escape hatch.
skills	godot-skill-create, godot-skill-generate	Author a new MCP tool as a C# file in the project, and regenerate the SKILL.md files from the tools the editor currently has registered. System tools — reachable over the server's /api/system-tools/ HTTP surface (like ping), not advertised to AI agents in tools/list.
runtime-errors	runtime-errors-get, runtime-errors-clear	Poll errors raised inside the running game (NOT the editor) — GDScript runtime errors, push_error/push_warning, shader errors, and C# unhandled / unobserved-Task exceptions, with multi-frame GDScript backtraces on Godot 4.5+. OFF by default — opt in with builder.WithRuntimeErrorCapture().

ping

• ping — Lightweight readiness probe; echoes a message back, or returns pong. A System tool: call it over /api/system-tools/ping (or godot-cli run-system-tool ping); it is not listed in tools/list.

node

• node-find — Find nodes in the active scene tree by path, type, or name.
• node-create — Create a new node under a parent (optionally instancing a .tscn sub-scene), optionally at a specific sibling index (negative counts from the end).
• node-modify — Set fields/properties on one or more nodes.
• node-set-parent — Reparent nodes within the scene tree.
• node-reorder — Move an existing node to a different position among its siblings (Node.MoveChild) — the only way to rearrange an existing scene short of delete-and-recreate.
• node-duplicate — Duplicate nodes together with their subtrees.
• node-delete — Delete nodes from the active scene.

scene

• scene-open — Open a res://*.tscn PackedScene in the editor.
• scene-save — Save an open scene back to its .tscn file.
• scene-create — Create a new scene asset in the project.
• scene-list-opened — List the scenes currently open in the editor.
• scene-get-data — Retrieve the root nodes / structure of a scene.

resource

• resource-find — Search the project for resources (.tres/.res).
• resource-get-data — Read a resource's serialized fields and properties.
• resource-modify — Modify a resource's properties.
• resource-create — Create a new resource asset.
• resource-move — Move / rename a resource, keeping .import sidecars consistent.
• resource-delete — Delete a resource from the project.

filesystem

• filesystem-list — Browse the res:// tree (file types + uids) via the editor file index.
• filesystem-reimport — Reimport files in the project.

script

• script-read — Read a .cs / .gd script file.
• script-create — Create a new script file.
• script-update — Update an existing script file's contents.
• script-delete — Delete a script file.
• script-attach-to-node — Attach a script to a node.
• script-validate — Validate GDScript (.gd) files and return structured parse/compile diagnostics.

screenshot

• screenshot-viewport — Capture the editor viewport as a PNG.
• screenshot-camera — Capture from a specific camera.
• screenshot-isolated — Render a node in isolation from a chosen angle.

editor

• editor-application-get-state — Read the editor application/run state.
• editor-application-set-state — Start / stop the running game.
• editor-selection-get — Get the current editor selection.
• editor-selection-set — Set the current editor selection.

console

• console-get-logs — Read the plugin's collected editor logs (with filtering). This includes the plugin's connection lifecycle diagnostics (connect/disconnect, drain-timeout, config save/load, skill-gen, dev-control, dispatcher, and runtime-capture warnings), which route through the same capture sink as its framework logs.
• console-clear-logs — Clear the collected log cache.

reflection

• reflection-method-find — Find C# methods (including private) across every loaded assembly.
• reflection-method-call — Call any C# method with input parameters and get the result.

runtime-errors (in-game; OFF by default — enable with builder.WithRuntimeErrorCapture())

• runtime-errors-get — Read captured in-game runtime errors (oldest-first, newest-kept page); poll only new errors via sinceSequence. Returns available:false when capture was never enabled, so an empty list is never mistaken for health.
• runtime-errors-clear — Clear the captured in-game runtime-error buffer (a no-op when capture is not enabled); the monotonic sequence counter is preserved.

skills (system tools — served on /api/system-tools/, not advertised to AI agents)

• godot-skill-create — Write a new C# (.cs) MCP tool file into the project. The tool becomes callable once the project is rebuilt (Godot builds C# out-of-band).
• godot-skill-generate — Regenerate every SKILL.md from the tools currently registered in the editor, into the selected AI agent's skills folder.

Requirements

• Godot 4.3+ — the C# / .NET (mono) edition. The addon csproj pins Godot.NET.Sdk/4.3.0 as its minimum floor; newer 4.x editors (4.4, 4.5) work.
• .NET 8 SDK (net8.0).

[!IMPORTANT] Godot-MCP requires the mono (C#/.NET) build of Godot — the standard (GDScript-only) build cannot compile the addon.

Installation

There are two things to install: the addon (the plugin files) and the two NuGet packages the addon's C# depends on. Godot compiles every .cs under your project into one assembly, so your project's .csproj must declare the same NuGet references the addon needs — otherwise the addon's C# will not compile.

Step 1: Add the addon

Pick one of the following ways to get the addons/godot_mcp/ folder into your Godot C# project.

Fully automated (recommended for terminal workflows): godot-cli install-plugin ./MyGodotProject does all of Step 1 and Step 2 in one command — it downloads addons/godot_mcp/ from the matching GitHub release, adds the two NuGet packages and the extension-catalog <EmbeddedResource> to your .csproj, and enables the plugin in project.godot, idempotently. Use --source <path>/addons/godot_mcp to install from a local copy offline. The manual Options A–C below remain for in-editor (Asset Library) and hand-managed installs.

Option A — Godot Asset Library (recommended)

The easiest path: install directly from inside the editor.

1. Open the AssetLib tab at the top of the Godot editor.
2. Search for Godot-MCP and open the asset.
3. Click Download, then Install — Godot unpacks the addon into your project's res://addons/godot_mcp/.

The Asset Library entry is published per release and always points at a tagged version, so an in-editor install gives you a known-good snapshot of the addon. (See note below if the entry is not visible yet.)

Option B — GitHub Release zip

Grab the latest godot-mcp-addon-<version>.zip from the Releases page and extract it into your project's root — the archive already contains addons/godot_mcp/..., so the files land at res://addons/godot_mcp/.

Option C — copy from source

Copy the addons/godot_mcp/ folder from this repository (or your clone) into your project's addons/ directory by hand.

---

After the files are in place (Options A–C), enable the plugin: Project → Project Settings → Plugins → Godot-MCP → Enable. (If you used the fully-automated godot-cli install-plugin above, the plugin is already enabled and the NuGet packages + extension-catalog embed are already added — skip straight to Step 3.) On a successful load the editor Output panel prints:

[Godot-MCP] plugin loaded

Asset Library availability. The in-editor AssetLib entry (Option A) appears after the maintainer's first submission is approved by the Godot Asset Library moderators. Until then, use Option B (GitHub Release zip) or Option C.

Step 2: Add the NuGet packages + the extension catalog embed

Add both PackageReferences and the extension-catalog <EmbeddedResource> to your project's .csproj (use these exact pinned versions — they must match the addon's Godot-MCP.csproj):

<ItemGroup>
  <PackageReference Include="com.IvanMurzak.ReflectorNet" Version="5.4.0" />
  <PackageReference Include="com.IvanMurzak.McpPlugin"   Version="8.3.0" />
</ItemGroup>

<!-- Embed the extension catalog so the Extensions panel populates (else it is EMPTY). -->
<ItemGroup>
  <EmbeddedResource Include="addons/godot_mcp/extensions.catalog.json" LogicalName="Godot-MCP.extensions.catalog.json" />
</ItemGroup>

Package	Version	Role
com.IvanMurzak.ReflectorNet	5.4.0	Reflection / serialization core
com.IvanMurzak.McpPlugin	8.3.0	MCP plugin client (transitively pulls McpPlugin.Common + ReflectorNet; carries the shared AgentConfig module)

The <EmbeddedResource> is as required as the NuGet pins: the addon's pure-managed extension registry reads the catalog at editor runtime via GetManifestResourceStream (no res:// / filesystem fallback), and because the addon ships as source its own <EmbeddedResource> does not carry into your project — so without this line your Extensions panel is empty. The LogicalName must be exactly Godot-MCP.extensions.catalog.json so the resource resolves identically to the addon's own assembly.

Run dotnet restore so the packages land in your NuGet cache, then build. No manual DLL copying is required — at editor runtime the addon's assembly resolver locates the DLLs in your NuGet global-packages folder by reading the build's *.deps.json. (If you prefer self-contained output, set <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> so the DLLs are copied beside your project assembly instead.)

Step 3: Install an AI agent

Choose a single AI agent you prefer — you don't need to install all of