Godot MCP

✨ AI Game Developer — Godot MCP

[](https://modelcontextprotocol.io/introduction) [](https://www.npmjs.com/package/godot-cli) ') [](https://godotengine.org/) [](https://godotengine.org/) [](https://dotnet.microsoft.com/) [](https://github.com/IvanMurzak/Godot-MCP/actions/workflows/release.yml) [](https://discord.gg/cfbdMZX99G) [](https://github.com/IvanMurzak/Godot-MCP/stargazers) [](https://hub.docker.com/r/aigamedeveloper/mcp-server) [](https://github.com/IvanMurzak/Godot-MCP/blob/main/LICENSE) [](https://stand-with-ukraine.pp.ua)

                                

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
• ✔️ 39 built-in Tools — A wide range of [MCP Tools](#tools-reference) across 11 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 to your .csproj, and enables
#    the plugin in project.godot — all idempotently
godot-cli install-plugin ./MyGodotProject

# 4. Pick an AI agent (Claude Code, Cursor, Copilot, …) and write its MCP config
godot-cli setup-mcp claude-code ./MyGodotProject

# 5. 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

# 6. 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 /addons/godot_mcp copies the addon from > a local directory instead of downloading it. Prefer the matching release version with > install-plugin --version if you need a specific addon build. The manual route (copy the > addon + add the NuGet packages yourself) is still documented under [Installation](#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](#quick-start)
• [Tools Reference](#tools-reference)
• [Requirements](#requirements)
• [Installation](#installation)
• [Step 1: Add the addon](#step-1-add-the-addon)
• [Option A — Godot Asset Library (recommended)](#option-a--godot-asset-library-recommended)
• [Option B — GitHub Release zip](#option-b--github-release-zip)
• [Option C — copy from source](#option-c--copy-from-source)
• [Step 2: Add the NuGet packages](#step-2-add-the-nuget-packages)
• [Step 3: Install an AI agent](#step-3-install-an-ai-agent)
• [Connect](#connect)
• [Cloud mode (default) — ai-game.dev](#cloud-mode-default--ai-gamedev)
• [Custom mode — your own server](#custom-mode--your-own-server)
• [Godot MCP Server setup](#godot-mcp-server-setup)
• [Local server — let the addon download & run it for you](#local-server--let-the-addon-download--run-it-for-you)
• [Build & run the server manually (advanced)](#build--run-the-server-manually-advanced)
• [Customize Tools](#customize-tools)
• [Runtime usage (in-game)](#runtime-usage-in-game)
• [Capturing in-game runtime errors](#capturing-in-game-runtime-errors)
• [Sample: a live game-state tool](#sample-a-live-game-state-tool)
• [Where the server URL and token come from](#where-the-server-url-and-token-come-from)
• [Security: opt-in only, default OFF](#security-opt-in-only-default-off)
• [How Godot MCP Architecture Works](#how-godot-mcp-architecture-works)
• [Building & contributing](#building--contributing)
• [License](#license)

Tools Reference

Godot-MCP ships 39 built-in tools grouped into 11 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](#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). | | node | node-find, node-create, node-modify, node-set-parent, node-duplicate, node-delete | Inspect and edit the active scene tree (the Godot analog of Unity GameObjects), driving EditorInterface on the main thread. | | 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. | | 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.

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).
• node-modify — Set fields/properties on one or more nodes.
• node-set-parent — Reparent nodes within the scene tree.
• 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.

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 to your .csproj, and enables the plugin in project.godot, idempotently. > Use --source /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-.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 are already added — skip straight to [Step 3](#step-3-install-an-ai-agent).) 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

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

| Package | Version | Role | | --- | --- | --- | | com.IvanMurzak.ReflectorNet | 5.3.1 | Reflection / serialization

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IvanMurzak
• Source: IvanMurzak/Godot-MCP
• License: Apache-2.0
• Homepage: https://ai-game.dev

Install and usage instructions live in the source repository linked above.