Godot MCP

Give your AI coding assistants hands, eyes, and deep debugging powers directly inside Godot Engine 4.x.

Godot MCP is an open-source Model Context Protocol (MCP) server that connects modern AI assistants (Codex, Anthropic Claude Desktop, Cursor, Antigravity, Roo Code, Cline, and custom agents) directly to Godot. The verified runtime target is Windows with Godot 4.6.3; other Godot 4.x minors need their own integration evidence.

Instead of copying and pasting GDScript snippets, guessing node hierarchy paths, or struggling to describe visual bugs to an LLM, Godot MCP provides a bidirectional control plane: agents can inspect scene trees, author 2D/3D nodes, build TileMaps, edit animations, step through code with a live DAP debugger, and capture high-resolution viewport screenshots for visual grounding.

Built with Godot MCP & Gemini 3.8 Flash

NEON SWARM is a fast-paced 2D cyberpunk top-down survival game created 100% autonomously by Gemini 3.8 Flash using Godot MCP—covering scene assembly, GDScript authoring, procedural audio, original artwork, and live DAP interactive debugging.

Related MCP server: godot-ai-mcp

Key Highlights & Superpowers

• 🎮 Complete Editor & Scene Control: Programmatically inspect, create, reparent, modify, and delete nodes, scenes, resources, and script signals without breaking scene structure.

• 🐞 Interactive DAP Debugger (Phase 9): Real-time breakpoint management, stepping (into, over, out), call stack inspection, and lazy variable evaluation during live game execution.

• 👁️ Visual Grounding & Viewport Capture: Capture 2D and 3D editor viewports as well as running game frames as PNGs, enabling multimodal AI models to visually inspect level layouts, shaders, and lighting.

• ⚡ Headless Process Manager (Phase 8): Run project validation, asset importing, automated tests, and background game instances without GUI dependencies—ideal for autonomous CI/CD or agent self-testing.

• 🛡️ Recoverable File Transactions: transaction.* stages declared files, checks preconditions and retains a journal and snapshots for compensation or manual recovery after a failed publication.

• 🧩 Structured Scene Batches: Prevalidate up to 64 native scene/resource operations, reject stale state, then apply them as one Undo/Redo action.

• 🔄 Project Events & Dependency Impact: Resume bounded project event streams and inspect direct, transitive, broken, and inbound resource references before changing assets.

• 📊 Deterministic Regression Evidence: Compare retained viewport captures pixel by pixel and evaluate runtime snapshots against caller-defined performance budgets.

• 📐 Walkway Geometry Preflight: Check complete 2D route footprints against declared colliders and measure endpoint gaps before running the game.

• 🎯 8 Bounded Tool Profiles: Select focused toolsets (minimal, core, 2d, 3d, navigation, ui, runtime, full) to drastically reduce LLM context token usage and latency.

Architecture Overview

Godot MCP uses a decoupled, secure two-tier architecture communicating over standard MCP stdio on the client side and an authenticated loopback WebSocket (127.0.0.1) on the engine side.

┌─────────────────────────────────────────────────────────────┐
│             AI Client (Codex, Claude, Cursor, Antigravity)  │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (stdio / JSON-RPC)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                  Godot MCP Server (Node.js 22+)             │
│  ├─ Tool Registry (194 tools across 8 profiles)             │
│  ├─ Headless Process Manager (Godot CLI runner)             │
│  ├─ DAP Client (Interactive debugger bridge)                │
│  ├─ Transaction & Snapshot Recovery Engine                  │
│  └─ Loopback WebSocket Server (127.0.0.1:<dynamic-port>)     │
└──────────────────────────────┬──────────────────────────────┘
                               │ Authenticated Handshake (Token)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    Godot 4.x Engine Instance                │
│  ├─ EditorPlugin (addons/godot_mcp)                         │
│  ├─ SceneTree & Resource Mutator                            │
│  ├─ 2D & 3D Viewport Grabbers                               │
│  └─ Runtime Autoload & Diagnostics Bridge                   │
└─────────────────────────────────────────────────────────────┘

Enterprise Hardening & Safety Architecture

Godot MCP includes bounded checks and recovery controls for autonomous work in trusted Godot projects:

• 🔒 Kernel-Level Project Lease (project-lease.ts): Multi-process mutual exclusion via Windows Named Pipes (\\.\pipe\godot-mcp-project-<sha256>). Ensures only one server or CLI process modifies a project concurrently, with automatic instant cleanup by the OS kernel if a process terminates abnormally.

• 🔄 Addon Journal & Rollback Barrier (addon-journal.ts): Addon installations and updates are staged with SHA-256 integrity verification. Startup detects a pending update and attempts rollback before normal work; an invalid journal or failed rollback stops the operation for inspection.

• 📦 Defensive Memory & Recursion Budgets (argument-budget.ts, serialization_budget.gd): Bound accepted inputs and serialized results; they reduce resource exhaustion but cannot sandbox project code.

• 🛡️ Reflection Guardrails (reflection-safety.ts, safety_policy.gd): Block dangerous reflective methods and restrict node mutations to the active edited scene tree; Godot and project scripts still run with their normal OS privileges.

• 📝 Journalled Multi-File Transactions & Checkpoints (transaction.*, checkpoint.*): Publish files sequentially with preconditions and compensation. An unsuccessful compensation retains evidence and requires recovery. External processes can observe intermediate files.

• 🐞 Interactive DAP Debugger (debug.*): Real-time breakpoints, stepping (into, over, out), stack frame inspection, and lazy variable expansion during live game runs.

• ⚡ Headless Process Manager (headless.*): Run project validations, asset imports, and automated tests in headless mode without GUI dependencies.

• 👁️ Visual Grounding (visual.*): High-resolution PNG captures of 2D/3D editor viewports and running game frames.

Tool Profiles

To keep LLM context sizes bounded, Godot MCP divides its 194 tools into 8 specialized profiles:

Tip: You can set a default profile in .godot-mcp/config.json via godot-mcp config <project> --tool-profile 2d or override it on server start with --tool-profile <name>.

Requirements & Compatibility Boundary

• Operating System: Windows 10/11 is the supported runtime. The project lease currently rejects Linux and macOS at server/CLI initialization with UNSUPPORTED_PLATFORM.

• Godot Engine: Verified against Godot 4.6.3-stable on Windows. Other Godot 4.x releases have capability probes but lack the complete integration matrix.

• Node.js: v22.0.0 or newer.

• Package Manager: npm (bundled with Node.js).

🚀 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:

1. 🔍 Discovers Godot: Automatically detects your installed Godot 4.x executable across standard Windows and system paths.

2. 📦 Installs Bridge Plugin: Copies addons/godot_mcp directly into your game folder.

3. ⚡ Activates Plugin: Enables the plugin automatically in project.godot (via Godot's headless CLI, no manual editor clicks needed).

4. 🤖 Configures Your AI Client: Automatically generates or updates its configuration (.codex/config.toml, .agents/mcp_config.json, .cursor/mcp.json, or Claude Desktop config).

Step 3: Open Your AI Editor and Godot

1. Open your project in your AI editor (Codex, Antigravity, Cursor, or Claude Desktop). Codex loads the project-local MCP config only after you trust the project. Restart an already-open client after changing its MCP configuration.

2. 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."

Verify Environment with Doctor

Ensure your environment, permissions, and Godot executable are properly configured at any time:

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

Alternative: Build from Source (Contributors)

git clone https://github.com/SrDarkoll/godot-mcp.git
cd godot-mcp
npm install
npm run build

Client Configuration

Add Godot MCP to your preferred AI assistant configuration:

Codex

godot-mcp init . --client codex writes a managed server entry to the project's .codex/config.toml:

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

Codex CLI, IDE extension, and local desktop tasks share the configuration on the same host. Trust the project and restart Codex 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 local setup codex recipe in the Codex guide is also available for source development. See OpenAI's MCP configuration guide for the client-side format.

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

Cursor

In .cursor/mcp.json (or Cursor Settings > Features > MCP):

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": [
        "-y",
        "@srdarkx/godot-mcp@0.6.3",
        "run",
        "--project",
        "C:/path/to/YourGodotProject"
      ]
    }
  }
}

Antigravity & Generic MCP Clients

Launch the server over stdio:

npx --yes @srdarkx/godot-mcp@latest run --project C:\path\to\YourGodotProject --tool-profile full

Example Prompts & Use Cases

Once connected, you can interact with your project naturally. Here are examples of what your AI can do:

🎨 Scene & Node Authoring

"Inspect the active scene tree. Add a CharacterBody2D named Player as a child of the root, attach a Sprite2D with texture res://icon.svg, and create a rectangular CollisionShape2D."

🗺️ Level Design & TileMaps

"Inspect res://levels/level_1.tscn. Create a TileMapLayer, configure its TileSet from res://tilesets/dungeon.tres, and paint a 12x2 floor platform at coordinate (0, 10)."

🐞 Interactive DAP Debugging

"Launch the game with the debugger attached. Place a breakpoint at line 35 of res://scripts/player.gd. When triggered, inspect the call stack and show me the value of velocity and health."

📸 Visual Inspection & Shaders

"Capture the 3D viewport of the current editor view. Inspect the visual appearance of the water shader on the lake mesh, check lighting reflections, and adjust the roughness property to 0.2."

🤖 Autonomous Verification Workflow

"Run workflow.run_check on res://scenes/test_arena.tscn. Run headless tests, capture the game frame after 2 seconds, verify there are zero script errors, and report a pass/fail verdict with evidence."

📐 Walkway Preflight

"Use geometry.validate_walkways to check CentralCross against its declared collision nodes and measure the gap to its connecting route before capturing a frame."

Safety & Reversibility

Godot MCP reduces risk with explicit permissions, previews, snapshots and recoverable publication. Review the result of any write to a trusted project:

1. Declared Transactions (transaction.*): Agents stage multiple file changes and publish them one by one after precondition checks. Failed publications attempt compensation; unresolved journals block further normal work until inspected. Other processes may observe intermediate writes.

2. File Checkpoints (checkpoint.*): Creates snapshot restore points before complex refactors, allowing one-command restoration of critical files.

3. Risk Preview (risk.preview): High-risk operations (such as file deletions or batch property overwrites) require explicit confirmation and permission checks.

4. Isolated Loopback Security: The WebSocket bridge binds strictly to 127.0.0.1 using short-lived tokens and randomized ports generated per session.

Project Structure

godot-mcp/
├── packages/
│   ├── protocol/       # Canonical JSON-RPC schemas, contracts, and TypeScript types
│   ├── server/         # Core MCP server, profiles, transaction manager, DAP client
│   ├── cli/            # CLI commands (init, doctor, config)
│   └── godot-addon/    # Godot 4 EditorPlugin (WebSocket bridge, viewport grabbers)
├── tests/
│   └── integration/    # Live Godot 4.x editor, runtime, headless & DAP test suites
├── docs/               # Comprehensive architecture, protocol, and tool documentation
└── scripts/            # CI scripts, code generators, and automated test runners

Running Tests Locally

You can run individual test suites using the supported npm scripts:

# Run unit tests across all packages (protocol, server, cli)
npm test

# Check type safety and tool schema synchronization
npm run typecheck
npm run check:tool-contracts

# Godot syntax and live integration require the Godot executable
$env:GODOT_BIN = "C:\Tools\Godot\Godot_v4.6.3-stable_win64.exe"
npm run check:godot

# Run live integration tests
$env:REQUIRE_GODOT_INTEGRATION = "1"
npm run test:integration

# Specific integration tiers
npm run test:integration:runtime    # Live game runtime & diagnostics
npm run test:integration:visual     # Viewport and game pixel capture
npm run test:integration:debugger   # DAP interactive debugger (Phase 9)
npm run test:distribution           # Packaged tarball distribution smoke test

To execute the complete 10-gate validation suite in a single automated run:

powershell -ExecutionPolicy Bypass -File scripts/run-all-gates.ps1 -GodotBin "C:\Tools\Godot\Godot_v4.6.3-stable_win64.exe"

Documentation Index

• Architecture Foundation

• Tool Registry & Profiles Guide

• Protocol RPC Specification

• Codex Client Setup

• 2D Power Tools

• 3D & Materials Power Tools

• Navigation & AI Power Tools

• UI & Animation Power Tools

• TileMap & TileSet Power Tools

• Runtime & DAP Debugger

• Visual Viewport Capture

• Walkway Geometry Validation

• Project Lease and Maintenance

• Transactions & Recovery

• Autonomous Verification Workflows

License

This project is licensed under the MIT License. See the LICENSE file for details.

Developed with passion for game development and AI engineering by SrDarkoll.