godot-mcp
A local Model Context Protocol server for Godot projects.
Static analysis of GDScript, scenes and resources; journaled edits; and Godot games and editors it starts, drives, captures and debugs — one static Rust binary that runs beside your project.
English · 简体中文 · Website · Documentation · Install · Quick start · Contributing
Why godot-mcp
Your MCP client talks to one local godot-mcp process, never to the Godot editor
directly, and the process works in your project the way a careful collaborator
would: it reads before it writes, it proves what it did, and it says so when it
cannot.
- Analysis without the engine. Project discovery and validation, GDScript symbols, references and impact, text scene and resource trees, and the dependency graph all answer on a machine with no Godot installed.
- Edits as transactions. File and script patches carry the expected SHA-256 of what they change; scene and resource batches are journaled. A crash mid-change is reconciled to the proven before- or after-state, or quarantined, before the next request is served.
- The real engine, pinned. Validation, import, tests and exports run against the Godot build you configure; CI checks every release against exact locked Godot builds from 4.4.1 to 4.7.1.
- Games and editors it owns. Start a game or an editor, send keyboard, mouse, action and sequence input, read the live scene tree, properties, signals and UI, take screenshots and recordings, and step through code over the editor's language server and debug adapter.
- Refuses rather than guesses. A binary
.scnanswersunsupportedwith the fix ("re-save it as text"); an outcome it cannot prove answersuncertain. There is no tool that runs arbitrary GDScript. - Local-first. stdio by default, with no port and no credential. Optional loopback HTTP accepts only a per-launch secret or an authenticated proxy hop.
- Verifiable packages. Static Linux (musl) and
crt-staticWindows builds, aMANIFEST.jsonthe binary checks itself against, a CycloneDX SBOM, and release archives attested by GitHub.
Install
Release installer
The installers pick the archive for your platform, refuse it unless its digest
matches the release's SHA256SUMS.txt, extract the whole package, run its
self-check, and put godot-mcp on your PATH.
# Linux x86_64, macOS on Apple silicon
curl -fsSL https://raw.githubusercontent.com/sunerpy/godot-mcp/main/scripts/install.sh | sh
# Windows x86_64, PowerShell 5.1+
irm https://raw.githubusercontent.com/sunerpy/godot-mcp/main/scripts/install.ps1 | iex
Pin a release with GODOTMCP_VERSION=vX.Y.Z. The package goes to
~/.local/share/godot-mcp (%LOCALAPPDATA%\godot-mcp on Windows); the scripts'
headers list every setting.
Release archives
Each archive is one package directory: bin/godot-mcp, the process supervisor
beside it, the GDScript bridge assets, an example configuration, the licences,
the SBOM and the schema tree. Keep it together — the server finds its supervisor
and assets next to its own executable. Verify an extracted package, and the
archive's build provenance:
godot-mcp self-check --package /path/to/godot-mcp-X.Y.Z-x86_64-unknown-linux-musl
gh attestation verify godot-mcp-X.Y.Z-x86_64-unknown-linux-musl.tar.gz --repo sunerpy/godot-mcp
Build from source
For an unreleased commit, or a platform without an archive, build the package for
the machine you are on (Rust 1.96.0 is pinned in rust-toolchain.toml; Linux
needs musl-tools):
git clone https://github.com/sunerpy/godot-mcp.git
cd godot-mcp
make dist # writes target/release-dist/godot-mcp-<version>-<target>.<ext>
Quick start
Point your MCP client at the binary and a project directory (the one holding
project.godot, or any directory below it):
{
"mcpServers": {
"godot-mcp": {
"command": "godot-mcp",
"args": ["serve", "--project", "/path/to/my-game", "--profile", "core"]
}
}
}
core is read-only. Choose the profile deliberately:
Engine-backed tools need a Godot executable. The server looks in the usual install
locations and on PATH; to choose one, set godot_binary in a configuration file
passed with --config (Configuration). Every tool
per profile is listed in the generated tool inventory;
client wiring for HTTP and reverse proxies is in MCP clients.
Using with an LLM
Install through the Install section, register the server with your client as above, then let the agent discover the rest:
- Call
capabilities.getandhealth.getfirst: they name the profile, what the host can run (engine, supervisor, display) and why anything is unavailable. - Send one request at a time and wait for its answer. The per-principal
concurrency limit is small, and a burst answers
operational limit subject_concurrency was exceeded. - Every mutating call carries an
idempotencyId; repeating a call with the same id returns the recorded outcome instead of acting twice. - An answer is a result or a structured error with a
code(invalid_input,not_found,conflict,unsupported,unavailable,uncertain, …).uncertainmeans the effect may or may not have happened; read before retrying. - stdout carries MCP frames only; diagnostics go to stderr.
Documentation
The full index is docs/README.md; the website, https://firlab.app/godot-mcp/, has the guide in English and Chinese.
Development
make help # every target
make check # fmt-check, clippy, workspace tests, locked build, cargo-deny
make dist # this platform's release archive
Work test-first; CONTRIBUTING.md and the
contributor workflow describe the gates. CI runs
every check of the release-gate catalogue, the packaged smokes on Linux, macOS and
Windows, and the workspace suite natively on macOS and Windows; CI Success is the
required check.
License
MIT. See LICENSE-MIT and THIRD-PARTY-NOTICES.md.
