Godot-MCP

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

Pickoneof the following ways to get theaddons/godot_mcp/folder into your Godot C# project.

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

Grab the latestgodot-mcp-addon-<version>.zipfrom theReleases pageand extract it into your project's root — the archive already containsaddons/godot_mcp/..., so the files land atres://addons/godot_mcp/.

After the files are in place (Options A–C),enablethe plugin:Project → Project Settings → Plugins → Godot-MCP → Enable. (If you used the fully-automatedgodot-cliinstall-pluginabove, the plugin is already enabled and the NuGet packages + extension-catalog embed are already added — skip straight toStep 3.) On a successful load the editor Output panel prints:

<ItemGroup> <PackageReference Include="com.IvanMurzak.ReflectorNet" Version="5.4.0" /> <PackageReference Include="com.IvanMurzak.McpPlugin" Version="8.1.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>

Thegodot-cli opencommand forwards these env vars for you via--mode,--url,--cloud-url, and--tokenflags.

The server itself is the shared, engine-agnosticGameDev-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 addonpinsthe server version it consumes (theServerVersionconstant inaddons/godot_mcp/Runtime/Connection/GodotMcpServerView.cs).

InCustom modethe plugin canhost its own MCP server— you don't have to build or launch anything by hand. Open the addon dock'sServercard while Custom mode is selected and use theLocal serverrow:

- Start Server— downloads the server build for thepinned server version, caches it, launches it, and the plugin connects to it.Stop Serverterminates it (it is also stopped automatically when you close the editor).
- The download is the per-platform release assetgamedev-mcp-server-<rid>.zip— pulled overHTTPS fromgithub.comonly, from theGameDev-MCP-Server releasetaggedv<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 (anexactversion match, so the editor plugin and the server it talks to never drift). The server is launched on the port from yourServer URL(defaulthttp://localhost:8080), over thestreamableHttptransport.

This mirrorsUnity-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 aGameDev-MCP-Server releasebinary (or use theaigamedeveloper/mcp-serverDocker image). Both transports are supported:streamableHttp(HTTP) andstdio.

# 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 stdio

Then point the plugin at it inCustom mode(GODOT_MCP_HOST=http://localhost:8080).

See theGameDev-MCP-Server READMEfor the full argument / environment-variable table, the Docker image, and the cross-platform build matrix.

Godot-MCP supports customMCP Tooldevelopment directly in your project code. A tool family is apartial classdecorated[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, …)mustrun 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) orvoidfor side-effect-only ops — never ad-hoc string formatting for parseable output. Usestring? optional = nullparameters (nullable + default) to mark them as optional for the LLM.

Two things make runtime mode different from editor mode, and both are deliberate:

The entry point isGodotMcpRuntime.Initialize(...)(namespacecom.IvanMurzak.Godot.MCP.Runtime). Write it once — e.g. from a Godotautoload's_Ready()so aSceneTreeexists:

using System.Reflection; using com.IvanMurzak.Godot.MCP.Connection; // GodotMcpConnectionMode using com.IvanMurzak.Godot.MCP.Runtime; // GodotMcpRuntime using McpServerConsts = com.IvanMurzak.McpPlugin.Common.Consts.MCP.Server; // AuthOption (none/oauth/token) 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 = McpServerConsts.AuthOption.token; // offline bearer-token auth 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):

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).