Skip to main content
Glama
farrasfadhils

Godot MCP Bridge

by farrasfadhils
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Local

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.

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

#

Category

Tools

Highlights

1

Project

7

Settings read/write, UID conversion

2

Scene

9

Create, open, play, stop, instance, save

3

Node

14

Add/delete/rename/move with UndoRedo, signals, groups

4

Script

8

CRUD, attach, validate, search with line numbers

5

Editor

10

Screenshots, execute GDScript, error log, reload

6

Input

7

Keyboard, mouse, action simulation, sequences

7

Runtime

19

Game inspection, frame capture, recording/replay, UI

8

Animation

6

CRUD, tracks, keyframes

9

AnimationTree

8

State machine, transitions, blend tree

10

TileMap

6

Cell operations (TileMapLayer for Godot 4.3+)

11

3D Scene

6

Mesh primitives, .glb import, lighting presets, PBR

12

Physics

6

Auto 2D/3D collision, raycasts, layers

13

Particles

5

GPU particles + fire/smoke/rain/snow/sparks presets

14

Navigation

6

Region, agent, bake, pathfinding

15

Audio

6

Player (auto 2D/3D), bus effects chain

16

Theme/UI

6

StyleBoxFlat, color/constant/font overrides

17

Shader

6

Templates (canvas_item, spatial, particles, sky)

18

Resource

6

.tres CRUD, autoload management

19

Batch

8

Find by type, bulk set, dependency analysis

20

Testing

6

Automated scenarios, assertions, stress testing

21

Analysis

4

Scene complexity, signal flow, unused resources

22

Profiling

2

FPS, memory, physics, rendering monitors

23

Export

3

Preset listing, build commands

Total

168

+ 4 core connection tools

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:

File

Purpose

Used by

addons/godot_mcp/skills.md

Complete 168-tool reference with workflows

All AI agents

AGENTS.md

Architecture + capability summary

Codex, Gemini, agents

CLAUDE.md

Quick reference + build commands

Claude Code

.github/copilot-instructions.md

Copilot-specific instructions

GitHub Copilot

References