Godot MCP Server

Godot MCP Server

godot-mcp is an MCP (Model Context Protocol) server for AI-assisted Godot 4.x development. It gives AI clients a structured way to inspect and change Godot projects instead of guessing at .tscn, .gd, .gdshader, .tres, or project.godot formats.

It exposes 99 tools across 13 categories for scene manipulation, script generation, shader creation, animation workflows, InputMap setup, audio routing/player setup, navigation setup, UI building, procedural generation, project setup, live editor control, and runtime automation.

How It Fits Together

Recommended companion: Pair this MCP with godot-claude-skills. godot-mcp provides the tools. The skill pack improves how an agent uses them, especially through its godot-interactive workflow.

Features

File-Based Tools (Always Available)

• Scene Tools: Read, write, and manipulate .tscn scene files
• Script Tools: Generate and analyze GDScript files
• Shader Tools: Create shaders with 11 preset effects (dissolve, outline, hologram, etc.)
• Resource Tools: Manage .tres resource files
• Animation Tools: Create and edit animation clips, keyframes, and scene animation setup
• Input Tools: Manage InputMap actions/bindings and apply control presets
• Audio Tools: Create bus layouts and configure AudioStreamPlayer nodes
• Navigation Tools: Set up navigation regions, agents, and links in scene files
• UI Tools: Create themes, menus, HUDs, dialogs, and responsive layouts
• Procedural Generation: Dungeons, tilemaps, and enemy wave configurations

Live Editor Tools (Requires Godot AI Bridge Plugin)

• Real-time scene tree inspection
• Live node manipulation with undo/redo support
• Run/stop scenes directly from your AI assistant
• Capture runtime errors and console output
• Select nodes in the editor
• Drive the running game with synthetic actions, pointer events, and text entry
• Capture viewport screenshots from the running game

Documentation

• Built-in Godot 4.x class documentation
• Searchable API reference for commonly used engine classes

Quick Start

1. Build the MCP server from source.
2. Point your MCP client at dist/index.js and pass --project /path/to/your/godot/project.
3. If you want live editor tools, copy addons/godot_ai_bridge into your Godot project and enable the plugin.
4. Start with godot_help, then connect to the editor if needed.

If you only want file-based scene/script/resource editing, you can skip the AI Bridge plugin and use the file tools directly.

If you are also using godot-claude-skills, prefer its godot-interactive skill for persistent inspect/edit/run/debug loops over godot-mcp.

# Start here for tool discovery
godot_help                           # Overview of all 99 tools
godot_help tool="godot_write_scene"  # Usage template for one tool
godot_help task="create a menu"      # Suggested tool chain for a task
godot_help category="workflows"      # Common multi-step workflows

# If the Godot editor is running with AI Bridge enabled
godot_connect
godot_editor_get_project_info
godot_editor_get_scene_tree

Installation

Option 1: From Source

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

Option 2: From npm (when published)

npm install -g @genai-gametools/godot-mcp

Configuration

Any MCP client that can launch a local process can run this server. The example below uses Claude Code / Claude Desktop.

The server uses the stable MCP TypeScript SDK v2 and supports both the 2026-07-28 protocol and 2025-era clients. Stdio remains the default transport.

Claude Code / Claude Desktop

Add to your MCP configuration (~/.claude/mcp_servers.json or Claude Desktop settings):

{
  "mcpServers": {
    "godot-mcp": {
      "command": "node",
      "args": [
        "/path/to/godot-mcp/dist/index.js",
        "--project",
        "/path/to/your/godot/project"
      ]
    }
  }
}

Command Line Options

godot-mcp [options]

Options:
  --project <path>     Path to Godot project directory (default: current directory)
  --port <number>      Editor WebSocket port (default: 6550)
  --transport <type>   MCP transport: stdio or http (default: stdio)
  --http-port <number> Stateless HTTP port (default: 3000)

Stateless HTTP

For clients that connect to a URL instead of launching a subprocess:

npm run build
node dist/index.js --transport http --http-port 3000 --project /path/to/project

Connect the client to http://127.0.0.1:3000/mcp. The HTTP transport creates a fresh MCP server for every request and advertises ttlMs: 0; 2025-era HTTP requests use the SDK's stateless compatibility mode and do not receive session IDs. The endpoint binds only to loopback and validates localhost Host and Origin headers to reduce DNS-rebinding exposure.

The Godot AI Bridge WebSocket is intentionally process-scoped. Consequently, godot_connect persists across otherwise stateless MCP HTTP requests, which is necessary for the live editor tools to remain useful.

File operations from this server are queued, including requests from different HTTP clients. Writes use atomic replacement and reject observed changes made since a file was read. Paths are checked against the real project root, including symlink targets. This coordinates one server process; it is not a cross-process lock or a multi-file transaction.

Scene edits preserve existing Godot literals, multiline values, and supported extra sections. Unsupported animation tracks and ambiguous rename references are rejected before writing. godot_init_project creates a project at its explicit projectPath and refuses conflicting files by default; overwrite: true explicitly allows replacing generated files in an existing project.

---

Coverage Roadmap

See docs/COVERAGE_MATRIX.md for:

• current subsystem coverage (Strong/Partial/Minimal/Missing)
• high-impact gaps
• phased implementation priorities
• the same info is available via godot_help category="coverage"

---

All 99 Tools

Scene Tools (8 tools)

File-based scene tools accept either scene-root-relative paths like UI/Label or live-editor style paths like Main/UI/Label.

Script Tools (6 tools)

Shader Tools (4 tools)

Built-in Shader Presets: flash, outline, dissolve, pixelate, wave, gradient_map, chromatic_aberration, vignette, crt, hologram, fresnel

UI Tools (12 tools)

Theme Presets: fantasy, sci-fi, minimal, retro, horror, mobile

Resource Tools (3 tools)

Animation Tools (8 tools)

Input Tools (6 tools)

Audio Tools (9 tools)

Navigation Tools (8 tools)

Procedural Generation Tools (3 tools)

Documentation Tools (4 tools)

Editor Tools (27 tools - Requires Plugin)

Project Tools (1 tool)

---

Godot AI Bridge Plugin

For live editor features, you need to install the Godot AI Bridge plugin in your Godot project.

What It Does

The AI Bridge plugin runs a WebSocket server inside the Godot editor that allows the MCP server to:

• Read and modify the live scene tree
• Run and stop game scenes
• Capture print output and errors from the running game
• Trigger editor actions (save, open scenes, etc.)

Installation

1. Copy the plugin folder to your Godot project:

   cp -r addons/godot_ai_bridge /path/to/your/project/addons/
   

2. Enable the plugin in Godot:

   • Open your project in Godot 4.x
   • Go to Project > Project Settings > Plugins
   • Find "Godot AI Bridge" and set it to Active

3. Verify it's running:

   • You should see [AI Bridge] Server started on port 6550 in the Output panel

Pairing and upgrades

Update the server and the project addon together, then restart or re-enable the plugin. Each activation creates a fresh private pairing file at .godot/godot-ai-bridge.json. Start the MCP server with --project pointing to that same project; godot_connect loads the credential automatically. POSIX credentials must belong to the current user with mode 0600. On Windows, access uses the project directory's inherited ACLs. Keep the pairing file private and out of version control.

The bridge requires the secret WebSocket subprotocol before accepting any RPC. Unpaired clients cannot invoke editor operations, regardless of their Origin. Godot's WebSocket API does not expose incoming Origin headers, so pairing is the access control. Paired clients have full editor capabilities, including GDScript execution. Old unpaired clients are no longer compatible. Connections are limited to loopback; a local tunnel can use the optional explicit token argument.

Runtime prints, warnings, and errors are read from the active project's debug/file_logging/log_path while a debug session runs. Enable debug/file_logging/enable_logging to use this capture. Responses label these entries source: "log_file" and include capture availability/status metadata; disabled or unavailable logging is reported explicitly. These are log entries, not structured engine stack traces. Incremental reads advance past completed lines only.

Plugin Structure

addons/godot_ai_bridge/
├── plugin.cfg           # Plugin metadata
├── godot_ai_bridge.gd   # Main EditorPlugin
├── runtime_bridge.gd    # Runtime automation harness (autoload)
├── ws_server.gd         # WebSocket server implementation
└── message_handler.gd   # JSON-RPC message handling

How It Works

The plugin uses Godot's EditorPlugin and EditorDebuggerPlugin APIs to:

1. WebSocket Server (ws_server.gd): Listens on loopback port 6550 and requires pairing before dispatch
2. Message Handler (message_handler.gd): Processes JSON-RPC requests
3. Debugger Plugin: Tracks runtime sessions and automation replies; standard output/errors are ingested from the configured runtime log
4. Runtime Harness (runtime_bridge.gd): Receives debugger messages inside the running game for input automation and screenshot capture

JSON-RPC Methods

The plugin responds to these JSON-RPC methods:

---

Example Usage

Once configured, you can ask your AI assistant:

Scene Creation

• "Create a new 2D platformer scene with a player and some platforms"
• "Add a Camera2D that follows the player"
• "Set up a tilemap for my level"

Script Generation

• "Generate a player controller script with WASD movement and jumping"
• "Create an enemy AI script that patrols and chases the player"
• "Write a state machine for managing game states"

UI Development

• "Create a main menu with play, settings, and quit buttons using the fantasy theme"
• "Build a HUD with a health bar, score counter, and minimap"
• "Generate a settings menu with audio and display options"

Shaders

• "Add a dissolve shader to the player sprite"
• "Create a CRT screen effect for the game"
• "Generate an outline shader for selected objects"

Procedural Content

• "Generate a 10x10 dungeon with 5 rooms"
• "Create a cave tilemap pattern that's 20x15"
• "Generate 10 waves of enemies with goblins and orcs"

Live Editing

• "Connect to Godot and show me the current scene tree"
• "Run the main scene and show me any errors"
• "Select the Player node in the editor"

Runtime Automation

• "Run the scene, tap jump, and tell me if the player leaves the ground"
• "Click the Play button and capture a screenshot to tmp/menu.png"
• "Type a player name into the focused LineEdit"

Documentation

• "Show me the CharacterBody2D documentation"
• "Search the docs for 'collision'"
• "What methods does Area2D have?"

---

Common Workflows

1. Create a Complete Character

1. godot_write_scene - Create character scene
2. godot_generate_script - Generate controller script
3. godot_generate_shader - Add visual effects
4. godot_add_node - Add collision shapes, sprites

2. Build Game UI

1. godot_ui_create_theme - Create consistent theme
2. godot_ui_create_menu - Build main menu
3. godot_ui_create_hud - Add in-game HUD
4. godot_ui_create_dialog - Add dialog system

3. Debug with Live Editor

1. godot_connect - Connect to Godot
2. godot_editor_run_scene - Run the game
3. godot_editor_get_output - Check console output
4. godot_editor_get_errors - Review any errors

4. Automate a Runtime Check

1. godot_connect - Connect to Godot
2. godot_editor_run_scene - Start the game in debug mode
3. godot_runtime_status - Confirm the runtime harness is ready
4. godot_runtime_tap_action / godot_runtime_click - Drive gameplay or UI
5. godot_runtime_capture_screenshot - Save visual evidence when needed

5. Generate Procedural Content

1. godot_generate_dungeon - Create dungeon layout
2. godot_generate_tilemap_pattern - Add tile patterns
3. godot_generate_wave_config - Configure enemies

---

Requirements

• Node.js 20+
• Godot 4.x (the regression matrix covers 4.3 and 4.7)

License

MIT

Contributing

Issues and pull requests welcome at github.com/alexmeckes/godot-mcp