Godot编辑器AI集成工具

Godot MCP

MCP (Model Context Protocol) server and Godot 4.x editor plugin that gives AI assistants full access to the Godot editor. Build, inspect, and debug Godot games through natural language.

Works with any MCP-compatible AI client: Claude Code, Claude Desktop, Cursor, Windsurf, and others.

How It Works

graph LR
    A1["AI Client (stdio)"] --> Server["In-Process MCP Server"]
    A2["AI Client (HTTP)"] -->|HTTP| Daemon["HTTP Daemon"]
    Server -->|WebSocket| Plugin["Godot Plugin"]
    Daemon -->|WebSocket| Plugin
    Plugin --> Exec["Command execution\nScene manipulation\nRuntime debugging"]

The system has two layers:

1. Node.js MCP server — speaks the MCP protocol to AI clients and translates tool calls into WebSocket messages
2. GDScript editor plugin — runs inside Godot, receives commands via WebSocket, executes them using the editor and engine APIs

Two transport modes:

• Stdio (default) — when spawned by an MCP client (Claude Code, Claude Desktop, Cursor), the server runs in-process and auto-starts a headless Godot in the background. No daemon, no proxy — the process IS the server. Tools are available immediately; Godot connects asynchronously.
• HTTP daemon (--daemon) — persistent HTTP server for multi-client setups where multiple AI clients share one Godot connection.

Each Godot project gets a unique port pair (derived from the project path via FNV-1a hash), so multiple projects can run in parallel without conflicts.

Features

61 Tools Across 11 Categories

File Tools (4) — Browse and search the project filesystem

• list_dir read_file search_project create_script

Scene Tools (11) — Create and modify .tscn scene files

• create_scene read_scene add_node remove_node modify_node_property rename_node move_node attach_script detach_script set_collision_shape set_sprite_texture

Script Tools (8) — Edit GDScript, evaluate expressions

• edit_script validate_script list_scripts create_folder delete_file rename_file eval_expression eval_editor_expression

Project Tools (20) — Query and configure project settings, run scenes

• get_project_settings get_input_map get_collision_layers get_node_properties get_console_log get_errors get_debugger_errors clear_console_log open_in_godot scene_tree_dump list_settings update_project_settings configure_input_map rescan_filesystem run_scene stop_scene is_playing classdb_query setup_autoload eval_editor_expression

Asset Tools (1) — Generate 2D sprites from SVG

• generate_2d_asset

Runtime Tools (6) — Inspect and interact with the running game

• game_screenshot game_scene_tree game_get_properties game_get_property send_input_action send_key_event

Visualizer Tools (5) — Debug overlays and performance monitoring

• debug_draw_overlay clear_debug_overlay highlight_node watch_property performance_stats

Lifecycle Tools (3) — Manage the Godot process

• start_godot stop_godot godot_process_status

Assert Tools (3) — Automated testing meta-tools

• assert_property assert_node_exists wait_for_condition

Status (1) — Built-in connection check

• get_godot_status

9 Read-Only Resources

Resources let AI clients pull project context without side effects:

Runtime Debugging

When the AI calls runtime tools (game_*, visualizer tools), the plugin automatically:

1. Injects a __MCPRuntimeBridge__ autoload into the project
2. Launches the scene with the debugger bridge active
3. Routes commands through Godot's EditorDebuggerPlugin message channel
4. Cleans up the autoload when the scene stops

This means the AI can screenshot the running game, inspect live node properties, draw debug overlays, watch property changes over time, and read performance metrics — all without modifying your game code.

Visualizer System

The visualizer draws on a CanvasLayer at z-index 100, above all game content:

• Shapes: rectangles, circles, lines, arrows, labels with configurable color and thickness
• Node highlighting: automatically adapts to Control (rect), Node2D (circle), or generic nodes (label)
• Auto-screenshot: debug_draw_overlay and highlight_node capture a screenshot after drawing so the AI sees the result
• Auto-expire: overlays clear after a configurable duration

Setup

Prerequisites

• Godot 4.2+ (tested on 4.6)
• Node.js 20+

Installation

Option A: Symlink (for development)

# Clone the repo
git clone https://github.com/elfensky/godot-mcp.git
cd godot-mcp/server && npm install && npm run build

# Symlink the addon into your Godot project
ln -s /path/to/godot-mcp/addons/godot_mcp /path/to/your-project/addons/godot_mcp

Option B: npx (coming soon)

npx @elfensky/godot-mcp --daemon

Enable the Plugin

1. Open your Godot project
2. Go to Project > Project Settings > Plugins
3. Enable Godot MCP
4. The plugin auto-starts the daemon if it detects the server in the symlinked repo

Configure Your AI Client

Add a .mcp.json to your Godot project root (next to project.godot):

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": ["@elfensky/godot-mcp"]
    }
  }
}

This works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP client that supports stdio. The server runs in-process, auto-discovers the Godot project from the working directory, and auto-starts a headless Godot in the background.

Alternative: streamable-http (for multi-client setups)

If you need multiple AI clients sharing one Godot session, use the HTTP daemon mode:

{
  "mcpServers": {
    "godot-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:6506/mcp"
    }
  }
}

Note: The port (6506) is the default. With --project, each project gets a unique port via hash. In daemon mode, check .godot/mcp-daemon.json for the actual port.

Configuration

Environment Variables

CLI Flags

node dist/index.js [flags]

--project <path>  Godot project path (enables dynamic ports + process management)
--port <n>        Override the HTTP port
--daemon          Force HTTP daemon mode (stdio is the default when stdin is piped)
--no-force        Don't kill existing processes on startup
--http            Accepted for backwards compat (no-op, HTTP is always on)

Port Assignment

Without --project, the server uses default ports 6505/6506. With --project, each project gets a unique port pair derived from its absolute path via FNV-1a hash (range 6505–8504). This means multiple Godot projects can run simultaneously without port conflicts.

In HTTP daemon mode, the daemon writes .godot/mcp-daemon.json with its actual ports so that plugins can discover it. In stdio mode, ports are used only for the internal WebSocket connection to Godot.

Architecture

Data Flow

graph TD
    subgraph Clients
        S["AI Client (stdio)"]
        H["AI Client (HTTP)"]
    end

    subgraph StdioServer["Stdio Mode (in-process)"]
        MCP1["MCP Server<br/>(server.ts)"]
        Bridge1["GodotBridge<br/>(WebSocket)"]
        MCP1 -->|"Tool validation<br/>Resource serving<br/>Screenshot encoding"| Bridge1
    end

    S -->|stdio| MCP1

    subgraph Daemon["HTTP Daemon Mode"]
        MCP2["MCP Server<br/>(server.ts)"]
        Bridge2["GodotBridge<br/>(WebSocket)"]
        MCP2 -->|"Tool validation<br/>Resource serving<br/>Screenshot encoding"| Bridge2
    end

    H -->|HTTP :auto| MCP2

    subgraph Godot["Godot Editor Process"]
        Client["MCPClient<br/>(WebSocket)"]
        Handler["CommandHandler<br/>(router)"]
        Procs["FileCommands<br/>SceneCommands<br/>ScriptCommands<br/>ProjectCommands<br/>AssetCommands<br/>RuntimeCommands<br/>VisualizerCmds"]
        Debugger["DebuggerPlugin"]
        Game["Running Game<br/>(__MCPRuntimeBridge__)<br/>screenshots · overlays · props"]
        Client --> Handler --> Procs
        Client --> Debugger --> Game
    end

    Bridge1 -->|"WebSocket :auto"| Client
    Bridge2 -->|"WebSocket :auto"| Client

Command Processing Pattern

The plugin uses Chain of Responsibility: the CommandHandler iterates registered processors until one handles the tool name. Each processor:

1. Declares its tools via get_supported_tools() -> PackedStringArray
2. Routes via handles_tool(name) -> bool
3. Executes via process_command(name, args) -> Dictionary
4. Returns {&"ok": true, ...data} or {&"ok": false, &"error": "message"}

WebSocket Protocol

Messages between server and plugin are JSON over WebSocket:

Screenshot Pipeline

For tools that produce images (game_screenshot, debug_draw_overlay, highlight_node):

1. GDScript captures the viewport to a PNG file on disk
2. Returns the absolute file path in the tool result
3. Server reads the PNG, encodes as base64
4. Returns as MCP ImageContent alongside text metadata
5. AI client renders the image inline

Testing

Server Tests (Node.js)

cd server
npm run build
npm test

194 tests covering initialization, tool listing, resource listing, WebSocket round-trip, session management, assert tools, lifecycle tools, offline handlers, port assignment, daemon discovery, protocol version negotiation, and tool manifest validation.

Plugin Tests (GDScript)

Run from any Godot project with the addon:

godot --headless --script res://tests/test_plugin.gd

44 tests validating class loading, processor instantiation, tool declarations, command routing, WebSocket client contracts, and protocol version presence.

Adding New Tools

1. Define the tool schema in server/src/tools/<domain>-tools.ts
2. Register in server/src/tools/index.ts
3. Implement the handler in addons/godot_mcp/commands/<domain>_commands.gd extending MCPBaseCommandProcessor
4. Register the processor in commands/command_handler.gd
5. Update the expected tool list in server/tests/tool-manifest.test.mjs
6. Rebuild: cd server && npm run build

Tool Conventions

• Descriptions: 1-2 sentences, action-oriented. Use CAPS for constraints (e.g., "RUNNING game" vs editor).
• Validation: Always validate inputs before executing. Return {&"ok": false, &"error": "..."}.
• Results: All handlers return Dictionary with &"ok": bool.
• Naming: snake_case, prefixed by domain (game_, debug_).

Contributing

This project uses GitHub Flow:

1. Create a feature branch from main: git checkout -b feature/my-change
2. Make changes, commit with clear messages
3. Open a pull request against main
4. After review and CI pass, merge to main
5. Tag releases with semantic versions: git tag v0.2.0

Versioning follows Semantic Versioning. The version lives in three places — keep them in sync:

• server/package.json (source of truth, read at runtime)
• addons/godot_mcp/plugin.cfg
• CHANGELOG.md

Compatibility

• Godot: 4.2+ (runtime debugging requires 4.2+, tested on 4.6)
• Node.js: 20+
• MCP Protocol: 2025-03-26
• Platforms: macOS, Linux, Windows

License

MIT