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
- ✔️ 36 built-in Tools — A wide range of MCP Tools across 10 families for operating the Godot Editor
- ✔️ C# & GDScript — Read, create, and update both
.csand.gdscripts, and attach them to nodes - ✔️ Scene & Node control — Build and edit the scene tree, open/save
.tscnscenes, mutate.tres/.resresources - ✔️ 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.devout of the box, or point at your own server - ✔️ Natural conversation — Chat with AI like you would with a human
Get up and running in a few steps using the godot-cli (the Godot analog of unity-mcp-cli):
Prerequisite: first add the addon files and the two NuGet packages to your project — see Installation Steps 1–2.
install-pluginbelow only flips theproject.godotenable flag; it does not copy the addon or add the NuGet pins, so the editor cannot load the plugin without them.
# 1. Install godot-cli
npm install -g godot-cli
# 2. Enable the godot_mcp addon in your Godot C# project (addon files + NuGet pins must already be present)
godot-cli install-plugin ./MyGodotProject
# 3. Pick an AI agent (Claude Code, Cursor, Copilot, …) and write its MCP config
godot-cli setup-mcp claude-code ./MyGodotProject
# 4. Open the Godot editor (auto-connects with the right GODOT_MCP_* env vars)
godot-cli open ./MyGodotProject
# 5. Wait until the plugin answers the readiness probe
godot-cli wait-for-ready ./MyGodotProjectThat's it. Ask your AI "Create 3 cubes in a circle with radius 2" and watch it happen. ✨
See the full CLI documentation for every command, editor-resolution order, and connection env vars.
- Quick Start
- Tools Reference
- Requirements
- Installation
- Connect
- Godot
MCP Serversetup - Customize Tools
- Runtime usage (in-game)
- How Godot MCP Architecture Works
- Building & contributing
- License
Godot-MCP ships 36 built-in tools grouped into 10 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 tools are available immediately after the addon is enabled —
no extra configuration required.
| 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 |
CRUD on C# (.cs) and GDScript (.gd) files, plus attaching a script to a node. |
| 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. |
Per-tool descriptions
ping
ping— Lightweight readiness probe; echoes a message back, or returnspong.
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.tscnsub-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 ares://*.tscnPackedScene in the editor.scene-save— Save an open scene back to its.tscnfile.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.importsidecars consistent.resource-delete— Delete a resource from the project.
filesystem
filesystem-list— Browse theres://tree (file types + uids) via the editor file index.filesystem-reimport— Reimport files in the project.
script
script-read— Read a.cs/.gdscript 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.
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).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.
- Godot 4.3+ — the C# / .NET (mono) edition. The addon csproj pins
Godot.NET.Sdk/4.3.0as 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.
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.
Pick one of the following ways to get the addons/godot_mcp/ folder into your Godot C# project.
The easiest path: install directly from inside the editor.
- Open the AssetLib tab at the top of the Godot editor.
- Search for Godot-MCP and open the asset.
- 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.)
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/.
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, enable the plugin:
Project → Project Settings → Plugins → Godot-MCP → Enable (or run
godot-cli install-plugin ./MyGodotProject, which flips the
same enable flag in project.godot — it does not copy the addon files, so the files from Option A/B/C
must already be present). 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.
Add both PackageReferences 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.3.1" />
<PackageReference Include="com.IvanMurzak.McpPlugin" Version="6.10.0" />
</ItemGroup>| Package | Version | Role |
|---|---|---|
com.IvanMurzak.ReflectorNet |
5.3.1 |
Reflection / serialization core |
com.IvanMurzak.McpPlugin |
6.10.0 |
MCP plugin client (transitively pulls McpPlugin.Common + ReflectorNet; carries the shared AgentConfig module) |
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.)
Choose a single AI agent you prefer — you don't need to install all of them. This is your main chat
window to communicate with the LLM.
- Claude Code (recommended)
- Claude Desktop
- GitHub Copilot in VS Code
- Antigravity
- Cursor
- Any other MCP-aware agent
Write the agent's MCP-client config with godot-cli setup-mcp <agent> ./MyGodotProject — it points the
client at the Godot server's <host>/mcp URL. See the
CLI documentation for the full list of
supported agents.
The plugin connects to an MCP server in one of two modes. The mode and its URL / token can be set in the
serialized config or overridden at process start with environment variables (handy for CI, headless runs,
and local dev). All variable names are the Godot analog of Unity-MCP's UNITY_MCP_*. The active mode
always recomputes from the environment, so a process-level override wins over the serialized config
without editing any file.
In Cloud mode the plugin connects to the hosted backend at https://ai-game.dev (the /mcp hub path
is appended automatically). This is the default connectionMode.
| Environment variable | Purpose | Default |
|---|---|---|
GODOT_MCP_CONNECTION_MODE |
Force the mode: Cloud or Custom (case-insensitive). |
Cloud |
GODOT_MCP_CLOUD_URL |
Override the cloud base URL. A trailing /mcp is stripped if present; a non-http(s) value falls back to the default. |
https://ai-game.dev |
GODOT_MCP_TOKEN |
Bearer token, routed to the active mode's token. Surrounding quotes are trimmed. | (none) |
In Custom mode the plugin connects to a server URL you supply (a local dev server, a self-hosted instance, etc.).
| Environment variable | Purpose | Default |
|---|---|---|
GODOT_MCP_CONNECTION_MODE |
Set to Custom to select this mode. |
Cloud |
GODOT_MCP_HOST |
The custom server URL. Must be an absolute http(s) URL or it falls back to the default. | http://localhost:8080 |
GODOT_MCP_TOKEN |
Bearer token (only needed if the server requires authorization). | (none) |
Example — boot the editor pointed at a local server:
export GODOT_MCP_CONNECTION_MODE=Custom
export GODOT_MCP_HOST=http://localhost:5300
# export GODOT_MCP_TOKEN=... # only if the server enforces authThe
godot-cli opencommand forwards these env vars for you via--mode,--url,--cloud-url, and--tokenflags.
In Cloud mode you don't run a server at all — the plugin talks to ai-game.dev. If you want to host
the server yourself (local dev, CI, or your own cloud), you have two options: let the addon download and
run the matched server binary for you (recommended), or run it manually (advanced).
The server itself is the shared, engine-agnostic
GameDev-MCP-Server — one server binary
(gamedev-mcp-server) serving Unity-MCP, Godot-MCP, and Unreal-MCP. It is released from its own repo on
its own version line; this addon pins the server version it consumes (the ServerVersion constant in
addons/godot_mcp/Runtime/Connection/GodotMcpServerView.cs).
In Custom mode the plugin can host its own MCP server — you don't have to build or launch anything by hand. Open the addon dock's Server card while Custom mode is selected and use the Local server row:
- Start Server — downloads the server build for the pinned server version, caches it, launches it, and the plugin connects to it. Stop Server terminates it (it is also stopped automatically when you close the editor).
- The download is the per-platform release asset
gamedev-mcp-server-<rid>.zip— pulled over HTTPS fromgithub.comonly, from the GameDev-MCP-Server release taggedv<ServerVersion>, so the asset URL is:https://github.com/IvanMurzak/GameDev-MCP-Server/releases/download/v<ServerVersion>/gamedev-mcp-server-<rid>.zip. The<rid>(platform runtime identifier — e.g.win-x64,osx-arm64,linux-x64) is resolved automatically for your machine; all seven published RIDs are supported (win-x64/x86/arm64,linux-x64/arm64,osx-x64/arm64). - The binary is cached under your project's
.godot/mcp-server/<rid>/folder (gitignored) and re-used on later launches; it is only re-downloaded when the pinned server version changes (an exact version match, so the editor plugin and the server it talks to never drift). The server is launched on the port from your Server URL (defaulthttp://localhost:8080), over thestreamableHttptransport.
Version pinning & security. The download URL is derived solely from the addon's pinned
ServerVersionconstant and your platform RID — there is no arbitrary-URL binary execution. The addon version and the server version are decoupled: bumping the consumed server is an explicit addon change (a newServerVersion), and the pinnedv<ServerVersion>release must already exist on GameDev-MCP-Server before an addon release that pins it. If the release asset can't be fetched (you're offline), the addon logs a warning and the local server simply doesn't start — fall back to the manual run below, or use Cloud mode. The download is skipped entirely under CI (theCI/GITHUB_ACTIONSenvironment), where no local server is hosted.
This mirrors Unity-MCP's self-hosted server flow: the editor plugin manages the pinned server binary for you instead of requiring a manual build.
To run the server as a standalone / cloud process, download a
GameDev-MCP-Server release binary (or use the
aigamedeveloper/mcp-server Docker image). Both
transports are supported: streamableHttp (HTTP) and stdio.
# HTTP transport on port 8080
./gamedev-mcp-server --client-transport streamableHttp --port 8080
# stdio transport — for local MCP clients that launch the server directly
./gamedev-mcp-server --client-transport stdioThen point the plugin at it in Custom mode
(GODOT_MCP_HOST=http://localhost:8080).
Choosing a transport: use
stdiowhen the MCP client launches the server binary directly (local use — the most common setup); usestreamableHttpwhen running the server as a standalone process or in the cloud and connecting over HTTP.
See the GameDev-MCP-Server README for the full argument / environment-variable table, the Docker image, and the cross-platform build matrix.
Godot-MCP supports custom MCP Tool development directly in your project code. A tool family is a
partial class decorated [AiToolType]; each tool method is decorated [AiTool("tool-name", …)] with a
[Description] on the method and on each parameter to help the LLM understand it.
Any Godot API call (
Node,Resource,EditorInterface, …) must run on the editor main thread — marshal it throughMainThread.Instance.Run(...)(ReflectorNet'sMainThreadis backed by the Godot main-thread dispatcher on plugin boot). Never touch engine objects off-thread.
[AiToolType]
public partial class Tool_MyFeature
{
[AiTool("my-custom-task", Title = "Do a custom task")]
[Description("Explain to the LLM what this does and when to call it.")]
public string CustomTask
(
[Description("Explain to the LLM what this parameter is.")]
string inputData
)
{
// ... work that does not touch the Godot API can run on this background thread ...
return MainThread.Instance.Run(() =>
{
// ... touch EditorInterface / Node / Resource here, on the main thread ...
return "[Success] Operation completed.";
});
}
}Return a structured data model (ReflectorNet-serialized) or void for side-effect-only ops — never ad-hoc
string formatting for parseable output. Use string? optional = null parameters (nullable + default) to
mark them as optional for the LLM.
Everything above runs the MCP connection inside the Godot editor (the [Tool] EditorPlugin boots
it for you). Godot-MCP can also run inside a running / exported game build (debug or release) —
the Godot analog of Unity-MCP's runtime mode. This lets an LLM read and drive your live game state:
imagine a Chess game whose bot logic you outsource to an LLM by exposing a couple of tools.
Two things make runtime mode different from editor mode, and both are deliberate:
- It never auto-connects. The editor plugin connects on boot; a game build does not. You write
the opt-in code and decide when (if ever) to call
Connect(). - There are no tools, prompts, or resources by default — strictly manual. The runtime ships zero
MCP tools, prompts, and resources. You register every
[AiToolType]tool,[AiPromptType]prompt, and[AiResourceType]resource yourself, in your own code — and each kind is independently optional (register prompts without any tools, or vice versa). (The addon's editor tool families are gated by#if TOOLSand don't even compile into a game build, so they can never leak in.)
The entry point is GodotMcpRuntime.Initialize(...) (namespace com.IvanMurzak.Godot.MCP.Runtime).
Write it once — e.g. from a Godot autoload's _Ready() so a SceneTree exists:
using System.Reflection;
using com.IvanMurzak.Godot.MCP.Connection; // GodotMcpConnectionMode, GodotMcpAuthOption
using com.IvanMurzak.Godot.MCP.Runtime; // GodotMcpRuntime
using Godot;
public partial class GameMcp : Node
{
private GodotMcpRuntimeHandle? _mcp;
public override async void _Ready()
{
// 1) Build the connection (default OFF — nothing connects yet).
_mcp = GodotMcpRuntime.Initialize(builder =>
{
builder.WithConfig(config =>
{
config.ConnectionMode = GodotMcpConnectionMode.Custom; // your own server
config.Host = "http://localhost:8080"; // prefer loopback
config.AuthOption = GodotMcpAuthOption.Required; // require a bearer token
config.Token = "your-secret-token";
});
// 2) Opt YOUR tools / prompts / resources in. Zero of each by default — this is the only way
// they get registered, and each kind is independently optional.
builder.WithToolsFromAssembly(Assembly.GetExecutingAssembly()); // [AiToolType] classes
builder.WithPromptsFromAssembly(Assembly.GetExecutingAssembly()); // [AiPromptType] classes
builder.WithResourcesFromAssembly(Assembly.GetExecutingAssembly()); // [AiResourceType] classes
// …or register specific families:
// builder.WithTools(typeof(GameMcpTools));
// builder.WithPrompts(typeof(GameMcpPrompts));
// builder.WithResources(typeof(GameMcpResources));
}).Build();
// 3) Connect — explicit, the security-required opt-in. Retries in the background while
// KeepConnected is true (the default).
await _mcp.Connect();
}
public override async void _ExitTree()
{
// 4) Disconnect on shutdown (or whenever you want to stop exposing tools).
if (_mcp is not null)
await _mcp.Disconnect();
}
}Builder surface (all fluent / chainable):
| Call | What it does |
|---|---|
GodotMcpRuntime.Initialize(configure) |
Begin configuring; returns a GodotMcpRuntimeBuilder. configure may be null for the zero-tool, env-configured default. |
builder.WithConfig(Action<GodotMcpConfig>) |
Set Host / Token / ConnectionMode / AuthOption in code. Multiple calls compose in order. |
builder.WithToolsFromAssembly(Assembly) |
Register every [AiToolType] class in an assembly (usually Assembly.GetExecutingAssembly()). |
builder.WithTools(params Type[]) |
Register specific [AiToolType] classes when a whole-assembly scan is too broad. |
builder.WithPromptsFromAssembly(Assembly) |
Register every [AiPromptType] class in an assembly. Independent of tools/resources. |
builder.WithPrompts(params Type[]) |
Register specific [AiPromptType] classes. |
builder.WithResourcesFromAssembly(Assembly) |
Register every [AiResourceType] class in an assembly. Independent of tools/prompts. |
builder.WithResources(params Type[]) |
Register specific [AiResourceType] classes. |
builder.WithoutMainThreadDispatcher() |
Skip the automatic main-thread-dispatcher bootstrap (only if you install your own autoload dispatcher). |
builder.Build() |
Finalize; returns a default-OFF GodotMcpRuntimeHandle. |
handle.Connect() / handle.Disconnect() |
Open / close the connection. handle.Dispose() tears it down on shutdown. |
Initialize().Build()also guarantees a main-thread dispatcherNodein the runningSceneTree(so tool handlers can marshal Godot API calls onto the engine main thread), unless you opt out withWithoutMainThreadDispatcher(). Call it once aSceneTreeis live (e.g. from an autoload_Ready).
A runtime tool is written exactly like an editor tool — a partial class decorated [AiToolType], each
method decorated [AiTool("tool-name", …)] with a [Description] on the method and each parameter. Any
Godot API call (Node, SceneTree, …) must run on the engine main thread — marshal it through
MainThread.Instance.Run(...) (ReflectorNet's MainThread, backed by the dispatcher Initialize()
bootstrapped for you).
This Godot analog of Unity-MCP's "Chess bot" sample exposes the live running SceneTree to the LLM —
a pure-managed game-ping round-trip plus a game-scene-tree-summary that reads real Node state:
using System.ComponentModel;
using com.IvanMurzak.McpPlugin; // [AiToolType], [AiTool]
using com.IvanMurzak.ReflectorNet.Utils; // MainThread
using Godot;
[AiToolType]
public partial class GameMcpTools
{
[AiTool("game-ping", Title = "Game Ping", ReadOnlyHint = true, IdempotentHint = true)]
[Description("Runtime readiness probe. Echoes 'message' back, or returns 'pong-from-game' when omitted.")]
public string GamePing(
[Description("Optional message to echo back. When null/empty, returns 'pong-from-game'.")]
string? message = null)
{
return string.IsNullOrEmpty(message) ? "pong-from-game" : message;
}
[AiTool("game-scene-tree-summary", Title = "Game Scene-Tree Summary", ReadOnlyHint = true)]
[Description("Summary of the LIVE running game's SceneTree (current scene + root child node names).")]
public SceneTreeSummary GameSceneTreeSummary()
{
// Touch the live SceneTree on the engine main thread — MainThread.Instance was installed by
// GodotMcpRuntime.Initialize(...). Touching Node APIs off the main thread would fault.
return MainThread.Instance.Run(() =>
{
var summary = new SceneTreeSummary();
if (Engine.GetMainLoop() is not SceneTree tree || tree.Root == null)
{
summary.CurrentSceneName = "<no-scene-tree>";
return summary;
}
summary.CurrentSceneName = tree.CurrentScene?.Name ?? "<none>";
summary.RootChildCount = tree.Root.GetChildCount();
foreach (var child in tree.Root.GetChildren())
summary.RootChildNames.Add(child.Name);
return summary;
});
}
}
// Structured result (ReflectorNet-serialized — never ad-hoc string formatting for parseable output).
public sealed class SceneTreeSummary
{
public string CurrentSceneName { get; set; } = string.Empty;
public int RootChildCount { get; set; }
public System.Collections.Generic.List<string> RootChildNames { get; set; } = new();
}Register it from the Initialize(...) block above (WithToolsFromAssembly(Assembly.GetExecutingAssembly())
picks it up automatically), connect, and the LLM can now call game-ping / game-scene-tree-summary
against your live game. Real example outsourcing bot logic: a chess-do-turn tool that calls into your
game controller on the main thread, plus a chess-get-board tool returning a structured board model.
Same
[AiToolType]/[AiTool]/MainThread.Instance.Run(...)contract as the editor Customize Tools section — the only difference is that in a game build you register the tools and you callConnect().
Tools are not the only thing you can expose — MCP also has prompts (reusable instruction templates an
LLM can request by name) and resources (addressable, read-only content the LLM can fetch by URI). They
register exactly like tools: a partial class decorated [AiPromptType] / [AiResourceType], with each
member decorated [AiPrompt(...)] / [AiResource(...)] and a [Description]. Register your prompt and
resource classes the same way you register tools — WithPromptsFromAssembly(...) /
WithResourcesFromAssembly(...) (or the by-type WithPrompts(...) / WithResources(...)) from the
Initialize(...) block above. Each kind is independently optional — a game can expose prompts and/or
resources with no tools at all.
using System.ComponentModel;
using com.IvanMurzak.McpPlugin; // [AiPromptType], [AiPrompt], [AiResourceType], [AiResource]
using com.IvanMurzak.McpPlugin.Common.Model; // Role, ResponseResourceContent
using com.IvanMurzak.ReflectorNet.Utils; // MainThread
using Godot;
// A PROMPT — a named, reusable instruction the LLM can request. Returns the prompt text; Role marks who
// the message is from. Set Enabled = false to ship a prompt registered-but-off until you flip it on.
[AiPromptType]
public partial class GameMcpPrompts
{
[AiPrompt(Name = "explain-game-state", Role = Role.User)]
[Description("Ask the assistant to summarize the current game state for the player.")]
public string ExplainGameState()
{
return "Read the live SceneTree via the game tools and explain the current game state in one paragraph.";
}
}
// A RESOURCE — addressable read-only content fetched by URI. Route is the URI template; the method
// returns ResponseResourceContent[]. Any Godot API access marshals onto the main thread, exactly like a tool.
[AiResourceType]
public partial class GameMcpResources
{
[AiResource(
Name = "Live SceneTree node names",
Route = "game://scene-tree/nodes",
MimeType = "application/json",
Description = "The root child node names of the live running game's SceneTree.")]
public ResponseResourceContent[] SceneTreeNodes(string uri)
{
return MainThread.Instance.Run(() =>
{
var names = new System.Collections.Generic.List<string>();
if (Engine.GetMainLoop() is SceneTree tree && tree.Root != null)
{
foreach (var child in tree.Root.GetChildren())
names.Add(child.Name);
}
var json = System.Text.Json.JsonSerializer.Serialize(names);
return new[] { ResponseResourceContent.CreateText(uri, json, "application/json") };
});
}
}Same independently-optional, manual-registration contract as tools. The
[AiPrompt]/[AiResource]attribute names,Roleenum, andResponseResourceContenthelper all come from the reusedcom.IvanMurzak.McpPluginpackage the editor path already uses — nothing Godot-specific to learn.
A game build never auto-loads the editor's saved config (that's an editor-only convenience). You supply host/token one of two ways — and they compose, with env winning over code at resolution time:
-
In code —
builder.WithConfig(c => { c.Host = …; c.Token = …; }), as above. -
Out-of-band —
GODOT_MCP_*process environment variables or a project.envfile (read live byGodotMcpConfig, so a build can be reconfigured without recompiling):Environment variable Values Description GODOT_MCP_CONNECTION_MODECloud/CustomConnection mode (a loopback host implies Custom).GODOT_MCP_CLOUD_URLURL Override the Cloud base URL (default https://ai-game.dev).GODOT_MCP_HOSTURL Custom-mode server host (default http://localhost:8080).GODOT_MCP_AUTH_OPTIONNone/RequiredWhether Custom mode sends a bearer token. GODOT_MCP_TOKENstring The bearer token (routed to Cloud or Custom by the active mode). GODOT_MCP_LOG_LEVELTrace…NoneLog-verbosity threshold. export GODOT_MCP_CONNECTION_MODE=Custom export GODOT_MCP_HOST=http://localhost:8080 export GODOT_MCP_AUTH_OPTION=Required export GODOT_MCP_TOKEN=your-secret-token
- Cloud mode (
GodotMcpConnectionMode.Cloud) connects tohttps://ai-game.dev(override withGODOT_MCP_CLOUD_URL). - Custom mode (
GodotMcpConnectionMode.Custom) connects to your own server — a local dev server, self-hosted, or a loopback address. This is the recommended mode for a shipped game (see below).
Exposing an MCP server inside a shipped game opens a remote-control surface: anything your registered tools can do, a connected MCP client can drive. Godot-MCP's runtime is built so this can only happen deliberately:
- Opt-in only / default OFF. Building a handle does not connect. Nothing happens until your code
calls
Connect(). There is no auto-connect path in a game build. - Zero tools by default. A runtime with no
WithTools…call registers nothing. The attack surface is exactly the set of tools you chose to register — no more. - No persisted-config auto-load. A game build never silently reads a saved config file; host/token
come only from your code or
GODOT_MCP_*env /.env. - Prefer loopback + a required token. For local tooling, bind to a loopback host
(
http://localhost:…/127.0.0.1) and setAuthOption = GodotMcpAuthOption.Requiredwith a realToken. Avoid exposing the connection on a public interface in a release build unless you have explicitly designed and secured that surface.
A short standalone copy of this contract lives in
docs/runtime-security.md.
Godot-MCP is a bridge between LLMs and the Godot editor. It exposes and explains Godot's tools to the LLM, which then understands the interface and uses the tools according to your requests.
On editor load, the [Tool] EditorPlugin (GodotMcpPlugin) boots the plugin: it installs a main-thread
dispatcher, builds a ReflectorNet Reflector
with Godot type converters, and opens a SignalR connection to an MCP server over the reused
com.IvanMurzak.McpPlugin client. The AI tools
it registers are then callable by any MCP-aware AI agent.
MCP — Model Context Protocol. In a few words, it is USB Type-C for AI, specifically for LLMs (Large
Language Models). It teaches the LLM how to use external features — such as the Godot Engine in this case,
or even your own custom C# method. Official documentation.
It is an application with a chat window. It may have smart agents to operate better, and embedded advanced MCP Tools. A well-built MCP client is 50% of the AI success in executing a task — which is why it is important to choose a good one.
It is the bridge between the MCP Client and "something else" — in this case the Godot editor. In Cloud
mode this is the hosted ai-game.dev backend; in Custom mode it is the shared
GameDev-MCP-Server host you run yourself (or let the
addon download and run for you).
An MCP Tool is a function the LLM can call to interact with Godot. These tools are the bridge between
natural-language requests and actual Godot operations. When you ask the AI to "create a node" or
"open a scene," it uses MCP Tools to execute the action. Tools have typed, described parameters; return
structured results; and are thread-aware (main-thread for Godot API calls, background-thread for heavy
processing).
Godot.NET.Sdk is a NuGet SDK, so no Godot binary is required to compile or unit-test:
dotnet restore Godot-MCP.sln
dotnet build Godot-MCP.sln --configuration Debug --no-restore # 0 errors required (CI gate)
dotnet test Godot-MCP.Tests/Godot-MCP.Tests.csproj --configuration Debug --no-buildA Godot 4.3+ editor is only needed for live behavioral verification of the engine-driving tools. See
CLAUDE.md for the full build/test/run
runbook, the editor-runtime assembly-load fix, conventions, and the headless testbed smoke.
Contributions are highly appreciated. Please give this project a star 🌟 if you find it useful!
- 👉 Fork the project
- Clone the fork and open it in a Godot 4.3+ (mono) editor
- Implement new things, commit, and push to GitHub
- Create a Pull Request targeting the original Godot-MCP repository,
mainbranch.
Apache-2.0 © Ivan Murzak
