@srdarkx/godot-mcp

v0.6.5

Published

6 days ago

Connects AI assistants like Codex, Claude and Cursor to Godot 4 to create and edit scenes, run games, debug code and capture screenshots.

0High
0Medium
0Low

srdarkx

Godot MCP on GitHub

Find the source code, setup guides and issue tracker in the repository. If Godot MCP helps your project, consider starring the repository.

Godot MCP connects AI assistants to Godot 4 so they can create and edit scenes, run games, debug code, and capture screenshots. The verified target is Windows with Godot Engine 4.6.3. Other Godot 4.x versions require their own integration checks.

Connect modern AI assistants (Codex, Cursor, Claude Desktop, Antigravity, Roo Code, Cline, and custom agents) directly to your running Godot editor and game runtime.

🚀 Quickstart: Connect Godot to your AI Assistant in 3 Steps

Step 1: Create or Open Your Godot Project

Open Godot Engine and create a new project (e.g. MyGame), or open an existing project containing project.godot.

Step 2: Run the Setup Command (Single Step)

Open a terminal in your project directory and run the command for your AI editor:

Codex setup is available in npm versions 0.5.1 and newer. See the Codex setup guide for project trust and configuration details.

Use @latest in the setup commands below. Without a version, npx can select an older local installation; check npx --yes @srdarkx/godot-mcp@latest --version if a supported client is rejected.

# For Codex
npx --yes @srdarkx/godot-mcp@latest init . --client codex

# For Google Antigravity / Gemini
npx --yes @srdarkx/godot-mcp@latest init . --client antigravity

# For Cursor
npx --yes @srdarkx/godot-mcp@latest init . --client cursor

# For Claude Desktop
npx --yes @srdarkx/godot-mcp@latest init . --client claude

(Tip: You can also pass a full path instead of ., e.g. npx --yes @srdarkx/godot-mcp@latest init C:\Projects\MyGame --client antigravity)

What the setup command does:

🔍 Discovers Godot: Automatically detects your installed Godot 4.x binary across standard Windows and system paths.
📦 Installs Bridge Plugin: Copies the hardened addons/godot_mcp EditorPlugin directly into your game folder.
⚡ Activates Plugin: Enables the plugin automatically in project.godot (via Godot's headless CLI, no manual editor clicks needed).
🤖 Configures Your AI Client: Automatically creates or updates .codex/config.toml, .agents/mcp_config.json, .cursor/mcp.json, or Claude Desktop config.

Step 3: Open Your AI Editor and Godot

Open your project in your AI editor (Codex, Antigravity, Cursor, or Claude Desktop). Codex loads project-local configuration only when you trust the project. Restart an already-open client after changing MCP configuration.
Open your project in Godot Engine. The editor plugin connects to the bridge over local WebSocket in ~1 second.

🎉 You're all set! You can now prompt your AI directly:

"Inspect the active scene tree and add a CharacterBody2D with a Sprite2D."
"Capture the 2D viewport to verify layout and shaders."
"Attach the DAP debugger, set a breakpoint in player.gd, and step through execution."
"Run headless project checks and verify zero GDScript errors."

🛠️ CLI Commands

`godot-mcp init [project-path]`

Initializes a Godot project for MCP connectivity.

# Auto-detect Godot and configure for Cursor
npx --yes @srdarkx/godot-mcp@latest init . --client cursor

# Specify custom Godot executable and Claude Desktop
npx --yes @srdarkx/godot-mcp@latest init C:\Projects\MyGame --godot C:\Tools\Godot_v4.6.3.exe --client claude

# Specify tool profile
npx --yes @srdarkx/godot-mcp@latest init . --client antigravity --tool-profile 2d

`godot-mcp upgrade [project-path]`

Version 0.6.1 adds a safe upgrade flow for existing installations:

npx --yes @srdarkx/godot-mcp@latest upgrade .

It preflights the installation, asks before stopping an active project session, backs up changes, migrates recognized project-local Codex launchers, installs the addon and runs doctor. Verification failures restore the earlier files. Other MCP entries and custom options are preserved. The command is not available in npm 0.6.0; see the upgrade guide.

Use --yes after upgrade to explicitly approve stopping the project session in automation, and --client codex to create Codex configuration if none exists. Reload an open Godot project and reconnect the client after success.

Starting with 0.6.2, upgrade . --dry-run previews the version, launcher and session changes without writing files or stopping the server. Verified source-checkout servers and Node scripts followed by a verified Godot MCP server entry can be migrated with one interactive confirmation. For automation, --replace-launcher separately approves replacing custom launcher behavior; --yes alone does not. See the upgrade guide.

Update reminders

Starting with 0.6.3, Windows CRLF launcher migration, linked CLI/server startup, incomplete addon detection and invalid configuration fields are handled directly. New installations use automatic loopback ports; upgrade . --bridge-port 0 explicitly changes an older fixed-port project with backup/rollback. For non-Git Godot projects, setup codex . --register-project-root adds the Godot root marker to Codex user settings while retaining other configuration. Plain setup codex stays read-only.

Starting with 0.6.3, automatic update notices appear on CLI stderr without changing JSON output, at most once a day per installed/latest version pair. MCP callers receive one notice per new version in the next tool response after the background check finishes; the assistant can relay it to the user. Versions 0.6.2 and earlier need one initial upgrade before they can provide these notices.

The notice includes npx --yes @srdarkx/godot-mcp@latest upgrade . for the Godot project, plus npm install -g @srdarkx/godot-mcp@latest for a global CLI or npm install @srdarkx/godot-mcp@latest for a local dependency. Updating npm alone does not update an addon or a pinned client launcher. Reload the addon and reconnect after upgrading each project; recognized project-local Codex entries are migrated automatically.

Checks use anonymous public npm metadata, a one-second request deadline and a daily cache. Offline failures are ignored, with a one-hour retry interval. Nothing updates automatically. Set GODOT_MCP_UPDATE_CHECK=0 to disable notices; CI, Vitest and npm offline mode also disable them. See update notices for cache locations and client configuration.

`godot-mcp run [options]`

Launches the MCP server over stdio for AI client consumption.

Starting with 0.6.3, Codex tool discovery and multiple chats can connect to one project session. Clients share the editor bridge and runtime, with separate MCP connections, tool profiles and approvals. Closing one client leaves the others connected. An older running server needs one restart during upgrade to load this behavior.

npx --yes @srdarkx/godot-mcp@latest run --project C:\Projects\MyGame --tool-profile full

`godot-mcp doctor [project-path]`

Runs comprehensive diagnostic checks on your environment, permissions, Godot executable, and bridge status.

npx --yes @srdarkx/godot-mcp@latest doctor .

Verifies:

Node.js runtime version (>= 22 required)
Godot 4.x binary detection and execution capability
Project structure (project.godot and res:// layout)
Addon installation integrity and SHA-256 manifest
Plugin activation in project.godot
Loopback WebSocket port availability

`godot-mcp config [project-path] [options]`

Inspects or repairs the .godot-mcp/config.json project configuration.

# Inspect current configuration
npx --yes @srdarkx/godot-mcp@latest config .

# Repair corrupted or invalid configuration
npx --yes @srdarkx/godot-mcp@latest config . --repair

🤖 AI Client Configurations

Codex (`.codex/config.toml`)

init --client codex writes a managed, project-local TOML entry while preserving other settings:

[mcp_servers.godot-mcp]
command = "npx"
args = ["--yes", "@srdarkx/[email protected]", "start", "C:/path/to/YourProject", "--tool-profile", "full"]

Trust the project in Codex and restart the local client after configuration changes. From that project, codex mcp get godot-mcp --json shows the configured launch command and project path; /mcp shows the active connection. The source checkout also offers godot-mcp setup codex as a read-only recipe for launching its compiled server during development. See the Codex setup guide and official Codex MCP documentation.

Cursor (`.cursor/mcp.json`)

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": [
        "-y",
        "@srdarkx/[email protected]",
        "run",
        "--project",
        "C:/path/to/YourProject"
      ]
    }
  }
}

Claude Desktop (`claude_desktop_config.json`)

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": [
        "-y",
        "@srdarkx/[email protected]",
        "run",
        "--project",
        "C:\\path\\to\\YourProject",
        "--tool-profile",
        "full"
      ]
    }
  }
}

🎯 194 Tools Across 8 Profiles

Godot MCP exposes 194 MCP tools partitioned into 8 profiles to optimize AI context window tokens:

🛡️ Enterprise Hardening & Safety

Godot MCP provides guarded operations for AI-assisted editing:

Kernel-Level Project Lease: Windows Named Pipes (\\.\pipe\godot-mcp-project-<sha256>) prevent concurrent conflicting processes. Instant kernel cleanup if a process terminates abnormally.
Addon Journal & Rollback: Addon updates are staged in .godot-mcp/addon-backups/ with SHA-256 verification and journal markers. Startup attempts to roll back interrupted updates and stops if recovery cannot be verified.
Defensive Serialization Budgets: Bound recursion (64 depth), item count (50,000) and strings (8 MB), with cycle detection via WeakSet.
Reflection Guard: Blocks 31 dangerous reflective methods (call_thread_safe, emit_signal, etc.) and restricts node mutations to the active edited scene tree.
Recoverable Multi-File Transactions: Stage declared file edits, verify preconditions and publish them sequentially with a journal and compensation. Other processes can observe intermediate writes; failed compensation leaves a journal requiring recovery.
Interactive DAP Debugger: Live breakpoint management, call stack inspection, lazy variable evaluation, and stepping (into, over, out) during runtime execution.
Visual and Geometry Checks: Capture 2D/3D editor viewports or a temporary close-up of a running game, resolve captures across sessions and validate walkway footprints against declared collisions before running.

📋 Requirements

Node.js: v22.0.0 or newer
Godot Engine: 4.6.3-stable verified on Windows; other 4.x versions require integration validation.
OS: Windows 10/11. The current project lease returns UNSUPPORTED_PLATFORM on Linux and macOS.

📄 License & Links

Repository: https://github.com/SrDarkoll/godot-mcp
Issues: https://github.com/SrDarkoll/godot-mcp/issues

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme