What godot-mcp does

Everything here is a tool your agent calls. The ones marked No engine answer from the project's files on a machine without Godot; the others need a Godot executable, and some of them a game or an editor that godot-mcp starts itself.

Read the project

• Project and settingsNo engine

  The project root, its name and main scene, every setting and every file, found from any directory inside the project.

• GDScriptNo engine

  Symbols, references, callers and impact across scripts, each edge with how sure it is.

• Scenes and resourcesNo engine

  The node tree, scripts, instances, groups and signal connections of text .tscn and .tres files.

• DependenciesNo engine

  What a scene or resource loads and what loads it, with the references that point at nothing.

Change it

• Files and scriptsNo engine

  Create, patch, move and delete, each against the SHA-256 of what it changes, so a stale edit is refused instead of applied.

• Scenes and resourcesNeeds Godot

  Node, property and connection changes as one batch, journaled as one transaction, through Godot or the open editor.

• Settings and assetsNo engine

  The main scene, autoloads, input actions, plugins and settings changed through typed operations, and binary assets uploaded in chunks.

• The editorNeeds Godot

  The godot_mcp add-on connects a running editor; a change to an open scene becomes one undoable editor action.

Run it

• Check, import and testNeeds Godot

  GDScript checked by Godot itself, the import pipeline, and the project's tests with exact counts.

• ExportNeeds Godot

  A preset exported with the exact templates of your Godot build, as a managed export you can follow and cancel.

• Run the gameNeeds Godot

  The main scene or any scene, in a window or headless, with its logs and status, until you stop it.

Drive and debug

• InputNeeds Godot

  Keys, mouse, actions and timed sequences, each released when its hold ends or the session stops.

• Live readsNeeds Godot

  The running scene tree, properties, signals and UI, read without changing the game.

• CapturesNeeds Godot

  Screenshots and short recordings, returned as artifacts with their SHA-256.

• DebuggerNeeds Godot

  Breakpoints, the stack, scopes and variables through the editor's debug adapter, and its language server's diagnostics.

From install to the first answer

1. 01

   Install

   Run the installer for your platform from the Install section below, or download an archive from GitHub Releases; the installer checks it against the release's SHA256SUMS.txt. No release is published yet, so for now build from source.

2. 02

   Register it with your client

   claude mcp add godot-mcp -- godot-mcp serve --project /path/to/my-game

   Any MCP client that starts a process takes the same command. It starts in the read-only core profile.

3. 03

   Ask about the project

   Ask your agent about a scene or a script. It calls capabilities.get and health.get to see what it may do here, then the analysis tools.

4. 04

   Grant more when you need it

   --profile full

   editor adds writes, runtime adds running and watching the game. Point godot_binary at your Godot build for the engine-backed tools.

Choose what it may do

A profile is the ceiling for everything the server may do to your project. core reads and changes nothing. editor adds the writes, each one journaled and checked against what it replaces. runtime adds running the project and watching it. There is no tool that executes arbitrary code, in any profile.

Profiles and answers · Tools and resources

Profile	Adds	Tools such as
core	Reads; changes nothing	project.info.get scene.tree.get gdscript.references.get
editor	Writes and the editor add-on	file.patch scene.batch.apply editor.addon.install
runtime	Runs and watches the game	project.run.start input.sequence.send runtime.screenshot.capture
full	All three	core editor runtime

A tool outside the profile is not listed. A listed tool whose engine, game or editor is not there answers unavailable and says which one.

A game it can play and watch

godot-mcp starts the game itself, with a probe of its own that changes nothing in the project. Your agent presses keys, reads the live scene tree and takes screenshots; an editor session adds breakpoints and the call stack. When the session ends, every input it held is released.

Games and editors · Managed sessions

To	Call	Notes
Run the game	project.run.start project.run.stop	In a window or headless, until its lifetime ends
Press and click	input.key.send input.mouse.send input.action.send input.sequence.send	Everything held is released
Read it live	runtime.tree.get runtime.properties.get runtime.signals.get runtime.ui.get	Changes nothing in the game
Capture it	runtime.screenshot.capture runtime.recording.capture	PNG or animated PNG, as an artifact
Debug it	editor.session.start debug.command	Breakpoints, stack and variables

At most four sessions run at once. Each belongs to the server that started it, and a server that starts after a crash ends the ones left behind.

The engine, exactly

Every Godot build the project supports is an exact patch version in one lock, with its official download and digest. CI runs the engine suite against each of them and smoke-tests every release archive against the newest, on its own platform.

Running the engine · Godot versions

Godot	CI runs	Platforms
4.7.1	Engine suite, export templates, display check, packaged smoke	Linux, macOS, Windows
4.6.1	Engine suite, export templates	Linux
4.5.1	Engine suite, export templates	Linux
4.4.1	Engine suite, export templates	Linux

Exact builds from one lock, each checked against its official SHA-256. The minimum supported version is 4.4.0.

Platforms

Every release has an archive for each platform below, built and smoke-tested on that platform against the locked Godot build.

Platform	Archive	Games and editors
Linux x86_64	x86_64-unknown-linux-musl, statically linked	A window under X11 or Wayland, or headless; contained by a process group, a delegated cgroup or a container adapter
macOS Apple silicon	aarch64-apple-darwin	A window in a logged-in user's session, or headless; contained by a process group or a container adapter
Windows x86_64	x86_64-pc-windows-msvc, crt-static	A window in a logged-on desktop session, or headless; contained by a Job Object

Intel macOS, Linux arm64 and Windows ARM64 have no archive; build from source there.

Where your project goes

godot-mcp works on your machine. It makes no network request of its own, apart from fetching your identity provider's signing keys when you configure OIDC.

Tool calls

Goes toYour MCP client

Over stdio the client and the server talk through two pipes. An answer carries the project data the call asked for, and nothing goes anywhere else.

HTTP, when you turn it on

Goes toA loopback listener

trusted_local accepts only requests that carry the per-launch secret; proxied_oidc only an authenticated proxy hop carrying one user's token.

The engine

Goes toYour machine

Godot runs locally from the build you configure, inside a process boundary the server owns. godot-mcp never downloads an engine or export templates.

Logs and captures

Goes toLocal files

Diagnostics go to stderr or a rolling file with secrets and source redacted. Screenshots, recordings and exports stay on disk as artifacts until their retention ends.

Install

No release is published yet, so the installers have nothing to download; until the first release, use the Source tab.

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/sunerpy/godot-mcp/main/scripts/install.sh | sh

Windows

irm https://raw.githubusercontent.com/sunerpy/godot-mcp/main/scripts/install.ps1 | iex

Source

git clone https://github.com/sunerpy/godot-mcp.git
cd godot-mcp && make dist

The install guide covers the archives, verifying a download and building from source.

What it does not do

• It does not run arbitrary GDScript or call arbitrary engine methods. No profile has such a tool.
• It does not download Godot or export templates. It uses the build and templates you installed.
• It does not edit binary .scn and .res files. It asks for them to be saved as text instead.
• It does not make an untrusted project safe to open. Loading a project runs its code.
• It is not a shared service. One server serves one project for one user.

Feedback

Bug reports and feature requests go to GitHub Issues. godot-mcp is MIT licensed and is not affiliated with the Godot Engine project.