Godot MCP Pro

Premium MCP (Model Context Protocol) server for AI-powered Godot game development. Connects AI assistants like Claude directly to your Godot editor with 187 powerful tools.

Architecture

AI Assistant ←—stdio/MCP—→ Node.js Server ←—WebSocket:6505—→ Godot Editor Plugin

• Real-time: WebSocket connection means instant feedback, no file polling
• Editor Integration: Full access to Godot's editor API, UndoRedo system, and scene tree
• JSON-RPC 2.0: Standard protocol with proper error codes and suggestions

What's in this repo

⚠️ This public repo only contains the free Godot addon/plugin. The MCP server (Node.js, required to connect AI assistants) is distributed as part of the paid package — one-time purchase, lifetime updates:

• Buy Me a Coffee: https://buymeacoffee.com/y1uda/extras
• itch.io: https://y1uda.itch.io/godot-mcp-pro

The paid zip includes the addon, the server/ directory with pre-built JavaScript, INSTALL.md, and AI-client instructions. If you cloned this repo and don't see a server/ folder, that's expected — grab the full package from one of the links above.

Quick Start

1. Install the Godot Plugin

Copy the addons/godot_mcp/ folder into your Godot project's addons/ directory.

Enable the plugin: Project → Project Settings → Plugins → Godot MCP Pro → Enable

2. Install the MCP Server

The server/ directory is only included in the full paid package (see above). After downloading and extracting the zip, run:

cd server
npm install
npm run build

3. Configure Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "godot-mcp-pro": {
      "command": "node",
      "args": ["/path/to/server/build/index.js"],
      "env": {
        "GODOT_MCP_PORT": "6505"
      }
    }
  }
}

4. Choose Your Mode

Godot MCP Pro offers four modes to fit any client's tool limit:

| Mode | Tools | Best For | |------|-------|----------| | Full (default) | 187 | Claude Code, Cline, VS Code Copilot, Cursor | | 3D (--3d) | 100 | Antigravity and other 100-tool-limit clients needing 3D | | Lite (--lite) | 88 | Windsurf, JetBrains Junie, Gemini CLI | | Minimal (--minimal) | 35 | OpenCode, local LLMs with small context |

--3d includes the core tools plus physics, AnimationTree and navigation, but omits uid_to_project_path, project_path_to_uid, compare_screenshots, clear_output, close_script, reload_open_scripts, set_anchor_preset and click_button_by_text to stay within the 100-tool cap.

{
  "mcpServers": {
    "godot-mcp-pro": {
      "command": "node",
      "args": ["/path/to/server/build/index.js", "--lite"]
    }
  }
}

Replace --lite with --minimal for the smallest footprint.

• Lite includes: project, scene, node, script, editor, input, runtime, and input_map tools.
• Minimal includes: 35 essential tools — project info, scene management, node CRUD, script editing, editor errors, input simulation, and runtime inspection.

5. CLI Mode (Alternative to MCP)

For clients without MCP support, or when you want zero context overhead, use the CLI directly from a terminal/bash tool. The CLI requires the server to be built first (Step 2).

# Top-level help — shows all command groups
node /path/to/server/build/cli.js --help

# Group help — shows commands in a group
node /path/to/server/build/cli.js node --help

# Command help — shows options for a command
node /path/to/server/build/cli.js node add --help

# Execute
node /path/to/server/build/cli.js project info
node /path/to/server/build/cli.js scene play
node /path/to/server/build/cli.js node add --type CharacterBody3D --name Player

Replace /path/to/ with the actual path where you extracted the files.

The CLI connects directly to the Godot editor plugin via WebSocket. It requires:

• Godot editor running with the MCP plugin enabled
• Server built (node build/setup.js install)
• An available port in the 6510-6514 range

Advantage: LLMs discover capabilities progressively via --help instead of loading all tool definitions upfront. This works with any LLM client that has terminal access, regardless of tool count limits.

6. Client Compatibility

| Client | Recommended Mode | Notes | |--------|-----------------|-------| | Claude Code | Full (default) | Deferred tool loading — minimal context cost | | VS Code Copilot | Full | Virtual Tools auto-group tools | | OpenAI Codex CLI | Full | MCPSearch defers overflow | | Cline | Full | No hard limit; use enabledTools to whitelist | | Roo Code | Full | No hard limit | | Windsurf | Lite | 100 tool limit | | JetBrains Junie | Lite | 100 tool limit | | Gemini CLI | Lite | ~100 client limit; use excludeTools for finer control | | Cursor | Full | Tool limit removed (Dynamic Context Discovery) | | OpenCode | Minimal or CLI | Models degrade past ~40 tools | | Local LLMs (LM Studio, etc.) | Minimal or CLI | Context window is the bottleneck |

7. Use It

Open your Godot project with the plugin enabled, then use Claude Code to interact with the editor.

All 187 Tools

Project Tools (10)

| Tool | Description | |------|-------------| | get_project_info | Project metadata, version, viewport, autoloads | | get_filesystem_tree | Recursive file tree with filtering | | search_files | Fuzzy/glob file search | | search_in_files | Search content in project files | | get_project_settings | Read project.godot settings | | set_project_setting | Set project settings via editor API | | uid_to_project_path | UID → res:// conversion | | project_path_to_uid | res:// → UID conversion | | add_autoload | Register autoload singleton | | remove_autoload | Remove autoload singleton |

Scene Tools (10)

| Tool | Description | |------|-------------| | get_scene_tree | Live scene tree with hierarchy | | get_scene_file_content | Raw .tscn file content | | create_scene | Create new scene files | | open_scene | Open scene in editor | | delete_scene | Delete scene file | | add_scene_instance | Instance scene as child node | | play_scene | Run scene (main/current/custom) | | stop_scene | Stop running scene | | save_scene | Save current scene to disk | | get_scene_exports | List @export variables of all scripted nodes in a scene file |

Node Tools (17)

| Tool | Description | |------|-------------| | add_node | Add node with type and properties | | delete_node | Delete node (with undo support) | | duplicate_node | Duplicate node and children | | move_node | Move/reparent node | | update_property | Set any property (auto type parsing) | | get_node_properties | Get all node properties | | add_resource | Add Shape/Material/etc to node | | set_anchor_preset | Set Control anchor preset | | rename_node | Rename a node in the scene | | connect_signal | Connect signal between nodes | | disconnect_signal | Disconnect signal connection | | get_node_groups | Get groups a node belongs to | | set_node_groups | Set node group membership | | find_nodes_in_group | Find all nodes in a group | | get_editor_selection | Get nodes selected in the Scene dock | | select_nodes | Select (and optionally focus/inspect) nodes in the Scene dock | | clear_editor_selection | Clear the Scene dock selection |

Script Tools (9)

| Tool | Description | |------|-------------| | list_scripts | List all scripts with class info | | read_script | Read script content | | create_script | Create new script with template | | edit_script | Search/replace or full edit | | attach_script | Attach script to node | | validate_script | Validate GDScript syntax | | close_script | Close a script editor tab; refuses on unsaved edits unless told to discard (Godot 4.7+) | | reload_open_scripts | Reload open scripts from disk, keeping unsaved buffers (Godot 4.7+) | | get_open_scripts | List scripts open in editor |

Editor Tools (15)

| Tool | Description | |------|-------------| | get_editor_errors | Get errors and stack traces | | get_output_log | Get output panel content | | get_editor_screenshot | Capture editor viewport | | get_game_screenshot | Capture running game | | execute_editor_script | Run arbitrary GDScript in editor | | clear_output | Clear output panel | | get_signals | Get all signals of a node with connections | | reload_plugin | Reload the MCP plugin (auto-reconnect) | | reload_project | Rescan filesystem and reload scripts | | compare_screenshots | Compare two screenshots | | set_auto_dismiss | Auto-dismiss blocking editor dialogs ("Reload from disk?" etc.) | | get_editor_camera | Get 3D editor camera position/rotation/FOV (+ snap settings on 4.6+) | | set_editor_camera | Move the 3D editor camera to frame a view | | get_unsaved_state | Report open scenes/scripts with unsaved changes (unsaved lists need Godot 4.7+) | | save_all | Save all open scenes and modified script buffers, report what was saved (scripts need Godot 4.7+) |

Input Tools (5)

| Tool | Description | |------|-------------| | simulate_key | Simulate keyboard key press/release | | simulate_mouse_click | Simulate mouse click at position | | simulate_mouse_move | Simulate mouse movement | | simulate_action | Simulate Godot Input Action | | simulate_sequence | Sequence of input events with frame delays |

Input Map Tools (2)

| Tool | Description | |------|-------------| | get_input_actions | List all input actions | | set_input_action | Create/modify input action |

Runtime Tools (20)

| Tool | Description | |------|-------------| | get_game_scene_tree | Scene tree of running game | | get_game_node_properties | Node properties in running game | | set_game_node_property | Set node property in running game | | execute_game_script | Run GDScript in game context | | capture_frames | Multi-frame screenshot capture | | record_frames | Record many frames to PNG files on disk | | monitor_properties | Record property values over time | | watch_signals | Log signal emissions on nodes over a duration | | start_recording | Start input recording | | stop_recording | Stop input recording | | replay_recording | Replay recorded input | | find_nodes_by_script | Find game nodes by script | | get_autoload | Get autoload node properties | | find_ui_elements | Find UI elements in game | | click_button_by_text | Click button by text content | | wait_for_node | Wait for node to appear | | find_nearby_nodes | Find nodes near position | | navigate_to | Navigate to target position | | move_to | Walk character to target | | batch_get_properties | Batch get multiple node properties |

Animation Tools (6)

| Tool | Description | |------|-------------| | list_animations | List all animations in AnimationPlayer | | create_animation | Create new animation | | add_animation_track | Add track (value/position/rotation/method/bezier) | | set_animation_keyframe | Insert keyframe into track | | get_animation_info | Detailed animation info with all tracks/keys | | remove_animation | Remove an animation |

TileMap Tools (6)

| Tool | Description | |------|-------------| | tilemap_set_cell | Set a single tile cell | | tilemap_fill_rect | Fill rectangular region with tiles | | tilemap_get_cell | Get tile data at cell | | tilemap_clear | Clear all cells | | tilemap_get_info | TileMapLayer info and tile set sources | | tilemap_get_used_cells | List of used cells |

Theme & UI Tools (8)

| Tool | Description | |------|-------------| | create_theme | Create Theme resource file | | set_theme_color | Set theme color override | | set_theme_constant | Set theme constant override | | set_theme_font_size | Set theme font size override | | set_theme_stylebox | Set StyleBoxFlat override | | setup_control | Configure Control/Container layout in one call | | `add_virtual_joystick