Command Palette

Search for a command to run...

UnylyUnyly
Browse all

Godot Cli

FreeMaintained

Cross-platform CLI tool for Godot-MCP (Skills & MCP). Resolves and launches the Godot editor with MCP connection env vars, runs MCP/system tools over HTTP, prob

GitHubEmbed

About

Cross-platform CLI tool for Godot-MCP (Skills & MCP). Resolves and launches the Godot editor with MCP connection env vars, runs MCP/system tools over HTTP, probes server health, configures AI agents (Claude Code, Cursor, VS Code, …), and enables/disables

README

Godot-MCP connects AI agents (Claude Code, Cursor, Codex, GitHub Copilot, Gemini or any other MCP client) to the Godot editor. The agent can read and change your scenes, nodes, resources and scripts, build and run C#, and look at screenshots. It is an editor addon with a companion CLI, godot-cli, and the Godot sibling of Unity-MCP.

Requirements: the .NET build of the Godot 4.3+ editor and the .NET 8 SDK, installed once. Your scripts can stay GDScript. The optional godot-cli needs Node.js 22.14+. Works on Windows, macOS and Linux.

Why Godot-MCP

✅ Godot 4.3 to 4.7 — every release is tested in CI on 4.3, 4.4, 4.5, 4.6 and 4.7
✅ Real C# builds — script-build runs dotnet build and returns the compiler errors
✅ GDScript checks — script-validate returns parse and compile diagnostics for .gd files
✅ Undoable, atomic edits — a query's changes apply all or nothing, one Ctrl+Z each
✅ Screenshots — viewport, a camera, or one node rendered alone, returned to the agent
✅ Runtime tools — logs, C# reflection and runtime errors from a running game (opt-in)
✅ Free cloud or fully local — ai-game.dev by default (no open ports), or a local server with no account
✅ No telemetry — the addon and godot-cli send no usage or analytics data

Works with GDScript projects

Your game code stays GDScript. The addon itself is C#, so the project needs a few one-time steps:

✅ Godot .NET editor — open the project in the .NET build of Godot 4.3+ (same project, same scenes)
✅ .NET 8 SDK — installed once per machine
✅ C# solution — existing project: Project → Tools → C# → Create C# solution; new: create-project --dotnet
✅ The addon — godot-cli install-plugin adds it, its NuGet references, and enables it

Does a GDScript-only project need a C# solution? Yes, once: the addon is C# and compiles into the project's C# assembly. Create C# solution adds a .csproj and a .sln file at the project root. Your .gd scripts, scenes and resources are not changed and run as before; the agent reads, writes and validates GDScript too. Exports then use Godot's .NET export templates and include the addon's small runtime assemblies, which stay inactive unless your code calls GodotMcpRuntime.Initialize() (how to leave them out).

A terminal session: godot-cli installs the addon, signs in, configures Claude Code and opens the editor

How it works

An AI agent talks MCP to a server (ai-game.dev, or a local gamedev-mcp-server); the server reaches the godot_mcp editor addon over SignalR; the addon runs tools on the Godot main thread

The addon connects out to an MCP server, and your agent connects to the same server and calls the addon's tools. The server is either a local GameDev-MCP-Server that the addon downloads and runs for you, or the hosted ai-game.dev relay. The addon opens no port of its own.

Stability

  • Versioning: the addon and godot-cli always ship with the same version number; read the release notes before you update.
  • What changes between versions: a release can move the NuGet versions the addon needs and the GameDev-MCP-Server version it downloads. godot-cli update (or install-plugin) writes the NuGet versions that match the addon you install, and the addon fetches its matching server itself.
  • Release gate: a release is cut only after the .NET tests, the CLI tests and the Godot 4.3–4.7 editor tests pass.
  • Change history: every GitHub release lists its merged changes; godot-cli also keeps a changelog.

Quick start

Install godot-cli (Node.js 22.14+) and add the addon to your project:

npm install -g godot-cli
godot-cli install-plugin ./MyGodotProject             # addon + NuGet references + enable the plugin

Then pick how the agent reaches the editor. Both are complete setups. Cloud is the addon's default: no open ports, no port conflicts with other programs, and free. Local keeps everything on your machine, for offline or air-gapped work.

Option A: local, no account. Tool calls stay on your machine.

  1. Set a token. Open the project in the Godot .NET editor. In the AI Game Developer dock choose Custom, set Authorization → token, press Generate, then Start Server. Note the Server URL (http://localhost:<port>, a port derived from the project path). Or choose a token yourself, open the editor with it from a terminal, then press Start Server: godot-cli open ./MyGodotProject --mode Custom --auth Required --token <token>
  2. Connect your agent with the same token:
godot-cli setup-mcp claude-code ./MyGodotProject --url http://localhost:<port> --token <token>

Without a token the local server uses authorization none. It listens on loopback only, so only programs on your own computer can reach it. In that case godot-cli open ./MyGodotProject starts the editor and its local server in one step and prints the URL for setup-mcp --url.

Option B: ai-game.dev cloud. Sign in once per machine; agent configs then carry a key bound to this project.

godot-cli login                                       # OAuth device login in the browser
godot-cli setup-mcp claude-code ./MyGodotProject      # write the agent's MCP config
godot-cli open ./MyGodotProject                       # build C#, start the editor, connect

Then ask your agent: "Create 3 cubes in a circle with radius 2."

To install from the editor's AssetLib tab, from a release zip, or by hand, follow docs/install.md: the project's .csproj then needs the addon's NuGet references (com.IvanMurzak.ReflectorNet, com.IvanMurzak.McpPlugin, and the editor-only com.IvanMurzak.Rql, com.IvanMurzak.CodeExec, com.IvanMurzak.CodeExec.Roslyn and Microsoft.CodeAnalysis.CSharp) at the versions of the release you install.

What goes through ai-game.dev

Only in Cloud mode. The relay is stateless: it routes tool calls between your agent and the editor without inspecting or persisting their contents, and it does not collect your conversations, source code, project files, assets or scene data. It records request metadata (IP address, time and duration, HTTP status code and request path, tool name and call count, request and response size, endpoint and client type) and MCP event metadata (event type, timing, status, session identifiers, the tool, prompt or resource name, and error details). These records are used primarily within a rolling 90-day window; the policy does not promise deletion at a fixed age. Details: Privacy Policy. In local mode the editor and the server talk only over localhost.

Connect your AI client

godot-cli setup-mcp <agent> ./MyGodotProject writes the config for you (godot-cli setup-mcp --list shows every agent id). The server entry is named ai-game-developer; <url> is the URL setup-mcp prints. In Cloud mode the entry also carries Authorization: Bearer agd_pk_…, a key that only reaches this project.

Claude Code — .mcp.json in the project
godot-cli setup-mcp claude-code ./MyGodotProject
{ "mcpServers": { "ai-game-developer": { "type": "http", "url": "<url>" } } }
Cursor — .cursor/mcp.json
godot-cli setup-mcp cursor ./MyGodotProject
{ "mcpServers": { "ai-game-developer": { "type": "http", "url": "<url>" } } }
VS Code (Copilot) — .vscode/mcp.json
godot-cli setup-mcp vscode-copilot ./MyGodotProject
{ "servers": { "ai-game-developer": { "type": "http", "url": "<url>" } } }
Codex — .codex/config.toml
godot-cli setup-mcp codex ./MyGodotProject
[mcp_servers.ai-game-developer]
enabled = true
url = "<url>"
tool_timeout_sec = 300
startup_timeout_sec = 30

In Cloud mode the key goes into http_headers.

Gemini CLI — .gemini/settings.json
godot-cli setup-mcp gemini ./MyGodotProject
{ "mcpServers": { "ai-game-developer": { "type": "http", "url": "<url>" } } }

Also supported: Claude Desktop, Visual Studio (Copilot), GitHub Copilot CLI, Rider (Junie), Antigravity, Cline, Open Code, Kilo Code and a generic custom client (CLI reference).

What the agent can do

Coverage: the agent can do virtually anything you can do in the Godot editor: scenes, nodes, resources, project settings, scripts, C# builds, screenshots and a running game.
Efficiency: the tools are compact, so the agent needs fewer calls and fewer tokens and works faster and cheaper. This is measured in tests: in RQL's agent evaluation on a sandbox game world, a task took 2–3 tool calls and about 8k tokens with RQL, against about 37 calls and 169k tokens with conventional find / get / set reflection tools.

You do not write queries: the agent reads the RQL guide that comes with the tools (rql-schema, the godot-rql skill) and writes them itself.

Capability Tools Ask your agent
Scenes and nodes rql-query, rql-mutate "Add a DirectionalLight3D to the main scene and save it."
Bulk edits rql-mutate "Hide every node whose name starts with Enemy."
Resources and project settings rql-query, rql-mutate "Add a jump input action bound to Space."
Look up the API rql-schema "Which Godot properties does a CharacterBody3D have?"
Scripts (GDScript and C#) script-create, script-update, script-attach-to-node, script-validate, script-read, script-delete "Write a GDScript that rotates this node and attach it."
Build C# script-build "Build the C# project and fix the errors."
Run C# in the editor script-execute "Count the MeshInstance3D nodes in the open scene."
See the result screenshot-viewport, screenshot-camera, screenshot-isolated "Take a screenshot of the viewport and check the lighting."
Running game (opt-in) console-*, reflection-*, runtime-errors-* "Check the running game for new runtime errors."

ping, session-close, godot-skill-create and godot-skill-generate are system tools for godot-cli and setup; agents do not see them. Every tool and argument: docs/tools.md.

The same tools work from a terminal, in the project folder (a headless editor starts when none is running):

godot-cli rql 'nodes | where name starts-with "Enemy" | set Visible = false'
godot-cli exec '1 + 2'        # → System.Int32: 3
godot-cli tools               # list the editor's tools

Security

Area What applies
Local server Listens on loopback only. Its default authorization is none, so any process on your machine can call it. Choose token in the dock, set GODOT_MCP_TOKEN, or open the editor with godot-cli open <path> --mode Custom --auth Required --token <token> to require a bearer token.
Origin checks The server answers 403 to a request with a non-allowed Origin header, in every authorization mode (DNS-rebinding defense).
Editor addon Opens no port; it connects out to the server. A dev-only control bridge on 127.0.0.1 starts only with GODOT_MCP_DEV_CONTROL=1.
Cloud Agent configs carry a key bound to one project; the editor uses your machine sign-in. Your account token goes only to ai-game.dev or a localhost server. The relay is stateless: it does not inspect or persist tool-call contents (Privacy Policy).
Stored tokens The editor saves its token as plain JSON in user://godot-mcp-config.json; treat that file as a secret.
Exported games Nothing runs in a game unless your code calls GodotMcpRuntime.Initialize(...) and Connect(), with only the tools you register. Error capture and in-game C# are separate opt-ins (runtime security).
Not protected Tool calls change your project and run C# in the editor: use version control, and never expose a server with authorization none to a network.

Details: Connection and server and GameDev-MCP-Server README.

Extensions

Extensions are optional NuGet packages that extend RQL; they add no tools of their own.

godot-cli install-extension com.IvanMurzak.Godot.MCP.CSG ./MyGodotProject
Extension Adds Requires
Animation AnimationPlayer libraries, tracks and keys
Beehave Behaviour trees and their nodes Beehave addon
CSG CSG shapes with validated dimensions
Dialogic Timelines and characters Dialogic addon, Godot 4.4+
GridMap GridMap settings, cell rows and cell editing
Navigation Navigation agents, regions, links, baking
Particles GPU particles in 2D and 3D
PhantomCamera Virtual cameras, follow and look-at Phantom Camera addon, Godot 4.4+
Terrain3D Terrain source, region size and materials Terrain3D addon, Godot 4.4+
Tilemap TileMapLayer cell rows and cell editing

Install a required third-party addon into the project yourself; the dock's Extensions section can install them all.

Documentation

Page What is in it
Manual installation AssetLib, release zip, NuGet references, agent setup
Connection and server Cloud and Custom modes, variables, the server
Tools reference Every tool and its arguments, screenshots, extensions
RQL in Godot-MCP Sources, functions, writes, undo and saving
Custom tools Writing tools, C# assembly reloads, the .NET 10 known issue
Runtime usage MCP inside a running game: setup, error capture, C# in the game
Runtime security What the in-game runtime guarantees and what you must do
CLI reference Every godot-cli command, exit codes and output formats
Architecture · Releasing · Extensions For contributors

Contributing

No Godot binary is needed to build and unit-test:

dotnet restore Godot-MCP.sln
dotnet build  Godot-MCP.sln --configuration Debug --no-restore
dotnet test   Godot-MCP.Tests/Godot-MCP.Tests.csproj --configuration Debug --no-build

Conventions, the headless editor smoke test and the main pitfalls are in AGENTS.md. Fork the repo and open a pull request against main. Questions and showcases: Discord.

Related: GameDev-MCP-Server · Unity-MCP · RQL · Code-Exec · ai-game.dev

License

Game developers can use everything freely, commercial games included. Godot-MCP is Apache-2.0. Its editor-side dependencies RQL and Code-Exec use the PolyForm Shield License 1.0.0, which restricts only companies that build competing AI tools for game development.

from github.com/IvanMurzak/Godot-MCP

Install Godot Cli in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE
unyly install godot-cli

Installs into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.

First time? Get the CLI: curl -fsSL https://unyly.org/install | sh

Or configure manually

Run in your terminal:

claude mcp add godot-cli -- npx -y godot-cli

Step-by-step: how to install Godot Cli

FAQ

Is Godot Cli MCP free?

Yes, Godot Cli MCP is free — one-click install via Unyly at no cost.

Does Godot Cli need an API key?

No, Godot Cli runs without API keys or environment variables.

Is Godot Cli hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Godot Cli in Claude Desktop, Claude Code or Cursor?

Open Godot Cli on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Changes

Versions and requested access over time.

  • New version published
  • New version published
  • New version published
  • New version published
  • New version published
  • New version published
  • New version published
  • New version published

Related MCPs

Compare Godot Cli with

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All development MCPs