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

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:

Project structure

godot-mcp/
├── addons/godot_mcp/              # Godot editor plugin (copy into your project)
│   ├── plugin.gd                  # Plugin entry; injects autoloads
│   ├── plugin.cfg
│   ├── websocket_client.gd        # WebSocket client + JSON-RPC dispatch
│   ├── command_router.gd          # Command router; registers all handlers
│   ├── commands/                  # 24 command modules (173 tool implementations)
│   │   ├── base_commands.gd       # Base class: Undo, runtime IPC, screenshots, etc.
│   │   ├── project_commands.gd
│   │   ├── scene_commands.gd
│   │   ├── node_commands.gd
│   │   ├── script_commands.gd
│   │   ├── editor_commands.gd
│   │   ├── input_commands.gd
│   │   ├── runtime_commands.gd
│   │   ├── animation_commands.gd
│   │   ├── tilemap_commands.gd
│   │   ├── theme_commands.gd
│   │   ├── profiling_commands.gd
│   │   ├── batch_commands.gd
│   │   ├── shader_commands.gd
│   │   ├── export_commands.gd
│   │   ├── resource_commands.gd
│   │   ├── physics_commands.gd
│   │   ├── scene_3d_commands.gd
│   │   ├── particle_commands.gd
│   │   ├── navigation_commands.gd
│   │   ├── audio_commands.gd
│   │   ├── animation_tree_commands.gd
│   │   ├── analysis_commands.gd
│   │   ├── test_commands.gd
│   │   └── android_commands.gd
│   ├── services/                  # Runtime autoload services
│   │   ├── mcp_runtime_bridge.gd  # In-game scene tree / properties / script execution
│   │   ├── mcp_input_bridge.gd    # Input event queue
│   │   └── mcp_screenshot_bridge.gd
│   └── utils/
│       ├── type_parser.gd         # Vector2 / Color type parsing
│       ├── node_utils.gd
│       └── resource_utils.gd
├── server/                        # Node.js MCP server
│   ├── src/
│   │   ├── index.ts               # MCP stdio entry
│   │   ├── godot-bridge.ts        # WebSocket server + JSON-RPC
│   │   ├── tools.ts               # Tool registration
│   │   └── tool-manifest.ts       # 173 tool definitions (name / description / params)
│   └── build/index.js             # Build output (MCP entry point)
├── example/                       # Demo Godot project
├── .mcp.json.example              # Sample MCP client config
├── README.md                      # English docs (default)
└── README.zh.md                   # Chinese docs

Requirements

• Godot 4.4+
• Node.js 18+
• Any MCP-capable client: Claude Code, Cursor, Codex CLI, Cline, Windsurf, etc.

Usage

1. Install the Godot plugin

Copy addons/godot_mcp/ into your Godot project’s addons/ directory:

cp -r addons/godot_mcp /path/to/your-game/addons/

Enable it in Godot: Project → Project Settings → Plugins → Godot MCP → Enable

Enabling the plugin injects 3 autoloads (MCPRuntimeBridge, etc.); they are removed when the plugin is disabled.

2. Build the MCP server

cd server
npm install
npm run build

The entry point after build is server/build/index.js.

3. Configure your AI client

Add the following to your MCP config file (replace paths with your actual paths):

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

See also .mcp.json.example in the repo.

4. Get started

1. First, open your project in Godot (with the plugin enabled)
2. Start your AI client and confirm the godot-mcp MCP server is connected
3. Ask the AI to operate the editor, for example:
   • “Get the current scene tree”
   • “Add a CharacterBody2D named Player under the root”
   • “Create a GDScript and attach it to Player”
   • “Play the current scene, then capture a game screenshot”
   • “Fill a grass area on the TileMap”

5. Example project

The example/ directory contains a runnable demo project:

godot --editor example/project.godot

How it works

1. The AI client calls an MCP tool (e.g. add_node) over stdio
2. The Node.js server converts the request to JSON-RPC and sends it over WebSocket to the Godot plugin
3. The plugin’s command_router dispatches to the matching handler, which calls EditorInterface and related APIs
4. The result travels back to the AI client along the same path

Runtime tools (e.g. get_game_scene_tree) additionally require:

• The editor to be in Play mode
• The MCPRuntimeBridge autoload polling user://mcp_runtime_req.json in the game process and writing responses

Adding a tool

To add a new MCP tool:

1. Create or edit a command class under addons/godot_mcp/commands/ and register the handler in get_commands()
2. Add the script path to the COMMAND_MODULES array in command_router.gd
3. Add the tool name, description, and parameter schema to TOOL_DEFINITIONS in server/src/tool-manifest.ts

Then rebuild the server:

cd server && npm run build

Known limitations

• Android tools: list_android_devices runs adb devices; deploy_to_android uses headless Godot export and adb install (requires an Android export preset and adb on PATH)
• Runtime tools: call play_scene first; the game process must load the MCPRuntimeBridge autoload; watch_signals listens for signal emissions on specified nodes while the game is running
• Cross-scene batch edits (cross_scene_set_property): modifies scene instances in memory — save the affected scene files manually
• Some editor APIs may differ across Godot minor versions; 4.4+ is recommended

License

MIT