Open-source Godot MCP server that lets AI assistants (Claude Code, Cursor, Codex, and more) control the Godot 4 editor directly through the Model Context Protocol (MCP).
概览
Open-source Godot MCP server that lets AI assistants (Claude Code, Cursor, Codex, and more) control the Godot 4 editor directly through the Model Context Protocol (MCP). - — node add/remove/edit and property changes go through the editor undo stack - — strings like Vector2(100, 200), #ff0000, Color(1,0,0) are converted automatically - — exponential backoff on the plugin side (1s → 60s) - — bidirectional ping/pong to keep the WebSocket alive - — standard protocol between the Godot plugin and the Node.
README
以下为原文 README 节选，完整内容请查看原文。
Godot MCP
Language: English | 简体中文
Open-source Godot MCP server that lets AI assistants (Claude Code, Cursor, Codex, and more) control the Godot 4 editor directly through the Model Context Protocol (MCP).
AI client ←—stdio/MCP—→ Node.js server ←—WebSocket:6505—→ Godot editor plugin
Overview
| Component | Role |
|---|---|
| Godot plugin | WebSocket client that receives JSON-RPC requests and executes commands via editor APIs |
| Node.js MCP server | Speaks stdio to AI clients; runs a WebSocket server (default port 6505) to forward tool calls |
| Command router | command_router.gd aggregates 24 command modules with 173 handlers |
| Runtime services | 3 autoloads (MCPRuntimeBridge / MCPInputBridge / MCPScreenshotBridge) use user:// IPC for in-game inspection, input simulation, and screenshots |
Core features
- UndoRedo integration — node add/remove/edit and property changes go through the editor undo stack
- Smart type parsing — strings like
Vector2(100, 200),#ff0000,Color(1,0,0)are converted automatically - Reconnect with backoff — exponential backoff on the plugin side (1s → 60s)
- Heartbeat — bidirectional ping/pong to keep the WebSocket alive
- JSON-RPC 2.0 — standard protocol between the Godot plugin and the Node.js server
Tool categories
173 MCP tools across 26 categories:
| Category | Tools | Highlights |
|---|---|---|
| Project | 7 | Project info, file search, UID conversion, project settings |
| Scene | 10 | Scene tree, create/delete/instance scenes, play/stop, @export variables |
| Node | 14 | CRUD, properties, signals, groups, resource attachment |
| Script | 8 | Script CRUD, attach, validation, full-text search |
| Editor | 13 | Editor/game screenshots, camera control, error log, screenshot diff, auto-dismiss dialogs |
| Input | 7 | Keyboard/mouse/action simulation, input map (incl. deadzone) |
| Runtime | 20 | In-game scene tree, properties, signal watching, record/replay, UI clicks, navigation |
| Animation | 6 | Tracks, keyframes, AnimationPlayer CRUD |
| TileMap | 6 | Cell read/write, rect fill, used-cell queries |
| Theme/UI | 7 | Theme creation, Control layout, color/font/StyleBox overrides |
| Profiling | 2 | FPS, memory, draw calls, physics monitors |
| Batch/Refactor | 9 | Batch add nodes, batch property updates, cross-scene edits, dependency/cycle detection |
| Shader | 6 | Shader CRUD, material assignment, parameter read/write |
| Export | 3 | Export preset list, export command generation |
| Resource | 6 | .tres read/write, Autoload register/remove |
| Physics | 6 | Collision bodies, physics layers (incl. layer name resolution), RayCast |
| 3D Scene | 6 | Mesh instances, camera, lights, environment, GridMap |
| Particle | 5 | GPU particles, materials, gradients, presets (fire/smoke/spark) |
安装
This server does not publish a one-line install command.
Open the repository installation guide 新手？先看 mcpskill.org 教程 →配置
{
"mcpServers": {
"godot-mcp": {
"command": "node",
"args": ["D:/godot-mcp/server/build/index.js"],
"env": {
"GODOT_MCP_PORT": "6505"
}
}
}
}