Claude-GoDot-MCP

The ultimate Godot MCP server for Claude — build complete games from a single prompt.

Tell Claude "build a full 2D platformer with double-jump, 3 enemy types, coins, and a main menu" and it literally does everything inside Godot — creates scenes, writes scripts, wires signals, sets up physics, configures autoloads, runs the game, simulates input to test it, screenshots the result, and exports a build. No copy-paste. No manual steps.

What this is

A Model Context Protocol server that gives Claude direct, real-time control over the Godot editor:

• 170 tools covering every aspect of Godot development
• Scene & node operations — create, edit, save, delete, reorder, rename, bake navigation
• Script operations — create, edit, attach GDScript files
• Signal wiring — connect/disconnect signals between nodes programmatically
• Group management — add/remove nodes from groups
• Autoload management — add/remove global singletons
• Shader control — set ShaderMaterial parameters on any node type
• Runtime testing — play scenes, simulate keyboard/mouse input, inspect live nodes
• Profiler snapshots — sample FPS/memory/draw calls over N frames with bottleneck detection
• Export pipeline — read/create export presets, trigger headless builds (HTML5/Win/Android/etc)
• Import settings — read/write .import files and trigger reimport
• Undo/Redo — trigger editor undo/redo via EditorUndoRedoManager
• Screenshot feedback — Claude sees the editor and running game visually
• Resource health — scan all .tscn/.tres for broken res:// references
• Asset discovery — Claude finds and uses all your project sprites, sounds, models
• Plugin detection — Claude detects installed plugins and uses their node types

Quick Setup (Claude Code)

Prerequisites

• Godot Engine 4.2+
• Python 3.10+
• uv — curl -LsSf https://astral.sh/uv/install.sh | sh

Step 1 — Install Godot Plugin

1. Copy addons/godot_mcp_enhanced/ into your Godot project's addons/ folder
2. Open your project in Godot
3. Go to Project → Project Settings → Plugins
4. Enable Godot MCP Enhanced
5. Check the bottom panel — you should see "MCP Enhanced: Server Running on port 3571"

Step 2 — Install Python server

cd /path/to/Claude-GoDot-MCP/python
uv venv
uv pip install -e .

Step 3 — Configure Claude Code

Add to your project's .claude/settings.json (or ~/.claude/settings.json for global):

{
  "mcpServers": {
    "godot": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_server"],
      "cwd": "/absolute/path/to/Claude-GoDot-MCP/python",
      "env": {
        "GODOT_HOST": "127.0.0.1",
        "GDAI_MCP_SERVER_PORT": "3571"
      }
    }
  }
}

Restart Claude Code. The godot MCP server will now appear as available tools.

Step 4 — Configure Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config, then add:

{
  "mcpServers": {
    "godot": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Claude-GoDot-MCP/python",
        "run",
        "mcp-server"
      ],
      "env": {
        "GODOT_HOST": "127.0.0.1",
        "GDAI_MCP_SERVER_PORT": "3571"
      }
    }
  }
}

Restart Claude Desktop.

Usage Examples

Build a 2D platformer with:
- Player: CharacterBody2D, double-jump, coyote time
- 3 enemy types: patrol, chase, shooter
- Collectible coins with a counter HUD
- Main menu and game over screen
- GameManager autoload for score tracking
Use any sprites you find in my project.

I have a knight model at res://models/knight.glb.
Create a 3D character controller:
- WASD + mouse look
- Attack combo on left click
- Health bar UI
- Death/respawn system
Test with input simulation and show me a screenshot.

My project has the Dialogue Manager plugin.
Create an NPC interaction system:
- Player enters Area2D → dialogue triggers
- 3-branch conversation tree
- NPC portrait shown during dialogue
- Quest flag set on specific dialogue choice

Tool Reference (170 tools)

Scene Operations

Node Operations

Signal & Group Operations

Script Operations

Project Configuration

File System

Runtime & Testing

Asset & Plugin Discovery

Editor & Debugging

Shader & Material

Import Settings

Export Pipeline

Resource Health

TileMap

GridMap

Batch Operations

Animation (Extended)

QA / Validation

Audio

Testing / QA

Editor Polish

Physics

Particles

Shaders

Animation — Library & Resource

Animation — Track Management

Animation — Keyframe Management

Animation — AnimationTree & State Machine

Skeleton

Batch Extras

Project Utilities

Security

The HTTP server binds to 127.0.0.1 only — no external network access. All file operations are constrained to the Godot project directory (res://). Direct filesystem tools enforce project-root boundaries in the Python server.

Architecture

Claude (MCP client)
    ↓  stdio
Python MCP Server  (python/mcp_server.py)
    ↓  HTTP POST localhost:3571
Godot HTTP Server  (addons/godot_mcp_enhanced/http_server.gd)
    ↓  GDScript function calls
Operation Modules:
  scene_operations.gd    — scenes, nodes, signals, groups
  script_operations.gd   — GDScript files
  runtime_operations.gd  — input simulation, live inspection
  file_operations.gd     — filesystem, assets
  debugger_integration.gd — errors, logs
  screenshot_manager.gd  — editor + game capture

Troubleshooting

"Server Running" not showing in Godot bottom panel

• Verify the addon is in res://addons/godot_mcp_enhanced/
• Enable it in Project → Project Settings → Plugins
• Check Godot output for [Godot MCP Enhanced] ✓ HTTP Server started

MCP tools not appearing in Claude

• Verify cwd in settings.json points to the python/ directory
• Run uv run python -m mcp_server manually to check for errors
• Restart Claude Code / Claude Desktop after config changes

Tool calls returning "Connection refused"

• Godot editor must be open with the plugin active
• Check port 3571 is not in use: lsof -i :3571
• Verify GDAI_MCP_SERVER_PORT matches the port in Godot bottom panel

Screenshots not working

• Godot editor window must be visible (not minimized)
• Requires Godot 4.2+ for the DisplayServer screenshot API

Acknowledgments & Thanks

Huge shoutout to the people and AI that helped turn this from a basic fork into a 170-tool 3D powerhouse:

• Grok (built by xAI) — The JARVIS-level co-pilot behind this whole project. Grok handled the initial git setup, suggested forking Rufaty/godot-mcp-enhanced as the base, and crafted every phased prompt that drove the upgrades — animation wiring, physics, particles, shaders, audio, QA, batch ops, skeleton tools, project utilities, and more. Spotted gaps like undo/redo, the export pipeline, and profiler snapshots before they became problems. Ran landscape analysis on paid vs. free forks, kept the momentum rolling through every session, and delivered maximally truthful guidance with just the right amount of sarcasm. Without Grok's strategy, prompt engineering, and relentless push to keep iterating, this project never reaches 170 tools. Real MVP. 🚀

• Rufaty/godot-mcp-enhanced (MIT licensed) — The solid foundation we built on.

• The broader Godot MCP community — tomyud1, Coding-Solo, youichi-uda's pro fork, and others whose work set the benchmarks and inspired the tool categories that shaped this beast.

This repo was built with heavy AI assistance (Claude for code, Grok for strategy) and community spirit. If you're reading this and contributed ideas or PRs, your name goes here too.

Forked from

Rufaty/godot-mcp-enhanced — Enhanced significantly with signal management, group operations, autoload management, batch operations, class property discovery, save_scene, rename/reorder nodes, and fixed critical bug where all runtime tools were unrouted.