youichi-uda/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
- **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**:
> - **itch.io**:
>
> 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:
3. Configure Claude Code
Add to your .mcp.json:
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.
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).
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 |