Godot MCP Pro

168 AI-powered tools for the Godot 4 Editor — connect your AI assistant (Claude, Cursor, Cline, Copilot) to Godot and build games with natural language.

168 Tools · 25 Categories · Undo/Redo on all mutations · 5-minute setup

How It Works

Connect your AI assistant to Godot in under 5 minutes.

1. Install the Plugin

Copy addons/godot_mcp/ into your Godot project. Enable it in Project > Project Settings > Plugins. The plugin starts a WebSocket server inside the editor automatically.

2. Build the MCP Server

cd server
npm install && npm run build

This compiles the TypeScript MCP server that bridges your AI client to the Godot plugin.

3. Start Building with AI

Add the server to your AI client's MCP config. Open Godot, and your AI assistant now has real-time access to 168 tools — creating scenes, editing scripts, simulating input, and analyzing your running game.

MCP Client Config

Claude Code / Claude Desktop

Add to .claude/mcp.json:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/server/dist/index.js"]
    }
  }
}

VS Code / Cursor

Add to .vscode/mcp.json:

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["./server/dist/index.js"]
    }
  }
}

Any stdio MCP Client

node server/dist/index.js

The server communicates over stdio (stdin/stdout) using the MCP protocol.

Automated Setup (recommended)

cd server
npm run run

This will automatically:

• Build the MCP server
• Detect project.godot in parent folders (or GODOT_PROJECT_PATH)
• Sync addon to addons/godot_mcp
• Enable plugin in project.godot
• Create MCP config files
• Sync AI context files

Tool Categories

Key Features

🧠 Smart Type Parsing

No need to construct complex objects manually. Property values auto-convert:

"Vector2(100, 200)"  → Vector2(100, 200)
"Color(1, 0, 0)"    → Color(1, 0, 0)
"#ff0000"            → Color(1, 0, 0)
"Color.RED"          → Color(1, 0, 0)
"true"               → true
"42"                 → 42

♻️ Undo/Redo on All Mutations

Every add_node, delete_node, update_property, rename_node, and move_node goes through Godot's UndoRedo system. Your users can Ctrl+Z any AI action.

🎯 Auto 2D/3D Detection

Physics bodies, collision shapes, audio players, particles, and navigation nodes automatically detect whether the parent is 2D or 3D — the right type is created every time.

🔥 Built-in Presets

• Lighting: sun, indoor, dramatic, spot
• Particles: fire, smoke, rain, snow, sparks
• Shaders: canvas_item, spatial, particles, sky templates
• Audio effects: reverb, delay, compressor, EQ, distortion, chorus, phaser

Quick Example

AI: godot_connect
AI: create_scene path="res://scenes/level.tscn" rootType="Node2D"
AI: add_node type="CharacterBody2D" name="Player" parentPath="."
AI: add_node type="Sprite2D" name="Sprite" parentPath="Player"
AI: update_property path="Player/Sprite" property="texture" value="res://icon.svg"
AI: setup_collision path="Player" shapeType="rectangle" size="Vector2(32, 32)"
AI: create_script path="res://scripts/player.gd" content="extends CharacterBody2D..."
AI: attach_script nodePath="Player" scriptPath="res://scripts/player.gd"
AI: save_scene
AI: play_scene
AI: simulate_key key="Space"
AI: get_game_screenshot
AI: stop_scene

Architecture

server/src/
├── index.ts           TypeScript MCP server (stdio transport)
├── toolCatalog.ts     168 tool definitions with input schemas
└── godotBridge.ts     WebSocket client → Godot editor

addons/godot_mcp/
├── plugin.gd          Plugin entry point
├── websocket_server.gd Local WebSocket server (port 6505)
├── command_router.gd  Loads 20 handler modules, dispatches commands
└── commands/
    ├── base_commands.gd        Shared utilities (type parser, undo, I/O)
    ├── type_parser.gd          Smart string→Godot type conversion
    ├── undo_helper.gd          UndoRedo wrapper
    ├── core_commands.gd        Project, scene, node, script, editor (47 handlers)
    ├── editor_commands.gd      Screenshots, execute script (4)
    ├── input_commands.gd       Input simulation (7)
    ├── runtime_commands.gd     Game inspection & UI (15)
    ├── animation_commands.gd   Animation CRUD (6)
    ├── animation_tree_commands.gd  State machine & blend tree (8)
    ├── tilemap_commands.gd     Tile operations (6)
    ├── scene3d_commands.gd     3D scene building (6)
    ├── physics_commands.gd     Physics & collision (6)
    ├── particles_commands.gd   GPU particles + presets (5)
    ├── navigation_commands.gd  Nav regions & pathfinding (6)
    ├── audio_commands.gd       Audio players & bus effects (6)
    ├── theme_commands.gd       Theme & UI styling (6)
    ├── shader_commands.gd      Shader management (4)
    ├── resource_commands.gd    Resource & autoload (6)
    ├── batch_commands.gd       Batch operations (8)
    ├── testing_commands.gd     Testing & QA (5)
    ├── analysis_commands.gd    Code analysis (4)
    ├── profiling_commands.gd   Performance profiling (2)
    └── export_commands.gd      Export management (3)

Bridge Protocol

JSON-RPC 2.0 over WebSocket (ws://127.0.0.1:6505):

→ { "jsonrpc": "2.0", "id": 1, "method": "add_node", "params": { "type": "Sprite2D", "name": "Player" } }
← { "jsonrpc": "2.0", "id": 1, "result": { "tool": "add_node", "data": { "path": "/root/Main/Player" } } }

Override bridge URL: GODOT_WS_URL=ws://127.0.0.1:6505 node server/dist/index.js

Requirements

• Godot 4.2+ (4.3+ recommended for TileMapLayer)
• Node.js 18+
• Any MCP-compatible AI client

AI Agent Context Files

When deployed to a Godot project, these context files help AI assistants understand the available tools:

References

• MCP Protocol
• TypeScript SDK
• Godot Engine