godot-mcp

# 🎮 Godot MCP — 1,969 [](https://modelcontextprotocol.io/introduction) [](https://godotengine.org) [](https://opensource.org/licenses/MIT) [](https://github.com/Reza2kn/godot-mcp) > **Godot > > 1,969 > --- ## 🚀 MCP - - - - - - --- ## ✨ Godot ## 🗂️ | | | |----------|---------------| | **Navigation** | `godot_start_here`, `godot_suggest`, `search_tools`, `get_workflow`, category browsing | | **Project** | Create, open, run, stop, export, configure Godot projects | | **Scene Editing** | Create/edit .tscn files, add/delete/rename/move/reparent nodes, set properties | | **2D Nodes** | Every 2D node: Sprite2D, CharacterBody2D, TileMap, Area2D, lights, joints, shapes... | | **3D Nodes** | MeshInstance3D, Camera3D, Lights, CSG, VehicleBody3D, Skeleton3D, GridMap... | | **UI / Control** | Button, Label, Container, ProgressBar, RichTextLabel, PopupMenu, TabContainer... | | **Runtime Control** | Move/rotate/scale nodes, set properties, spawn scenes — while the game runs | | **Physics** | Forces, impulses, joints 2D/3D, raycast, spherecast, SoftBody3D, VehicleBody3D | | **Audio** | Play/stop/pause, bus management, 3D spatial audio, audio effects, pooling | | **Camera** | Camera2D/3D, FOV, zoom, SpringArm3D, SubViewport, XR camera | | **Scripts & Signals** | Read/write GDScript, connect/emit signals, inspect methods and class hierarchy | | **GDScript Templates** | 100+ ready-to-use scripts: platformer, FPS, AI enemy, dialogue, inventory... | | **Animation** | AnimationPlayer, AnimationTree, state machine, blend times, track editing | | **Rendering** | WorldEnvironment, fog, glow, tone mapping, sky, VisualShader node graph | | **Resources** | TileSet, SpriteFrames, Materials, Fonts, Gradients, AnimationLibrary | | **Navigation Mesh** | NavigationAgent2D/3D, NavigationRegion, pathfinding, mesh baking | | **XR / VR / AR** | XRInterface, XRController, XRAnchor, world scale, tracking state | | **Editor Plugin** | Live editor: select nodes, undo/redo, save scene, inspect, reimport assets | | **File I/O** | Read/write files, list directories, JSON, CSV, binary, zip archives | | **Time & Crypto** | Unix time, SHA256, MD5, UUID, base64, datetime conversion | | **Networking** | ENet, WebSocket, HTTP, multiplayer peer setup | | **Diagnostics** | Validate scenes, find missing scripts, check collisions, project analysis | --- ## 🧭 > > ### 🔍 ```bash GODOT_MCP_DISCOVERY_MODE=true ``` | | | |------|-------------| | `godot_start_here` | Explains the whole system in one call — always call this first | | `godot_suggest` | `task="make a character jump"` → returns 3-5 perfect tool names | | `godot_call` | **Universal dispatcher** — calls any of the 1,969 tools by name | | `search_tools` | Keyword search across all tool names | | `list_tool_categories` | Shows all categories with counts | | `list_tools_in_category` | Shows all tools in one category | | `get_beginner_guide` | Step-by-step Godot MCP walkthrough | | `get_workflow` | Structured workflow for platformer, FPS, audio, UI, etc. | | `explain_godot_concept` | "What is a CharacterBody2D?" → real explanation | | + 11 core tools | `create_project`, `run_project`, `create_scene`, `create_script`, etc. | ### 🔥 ```bash # Default. No env var needed. ``` --- ## 🛠️ ``` ┌────────────────────────────────────────────────────────────┐ │ AI Model (Claude / GPT / Ollama) │ └───────────────────────────┬────────────────────────────────┘ │ MCP protocol (stdio) ┌───────────────────────────▼────────────────────────────────┐ │ Godot MCP Server (Node.js / TypeScript) │ └─────┬──────────────────────┬──────────────────┬────────────┘ │ │ │ ▼ ▼ ▼ 🖥️ Headless Godot 🎮 TCP :9090 ✏️ TCP :9091 File/resource ops Live game control Live editor control No game needed Requires run_project Requires plugin ``` | | | | |------|-------|---------| | **Headless** | Scene editing, resources, scripts, exports | Just Godot installed | | **Runtime :9090** | Move nodes, spawn, physics, audio, camera | `run_project` first | | **Editor :9091** | Select nodes, undo/redo, save, inspect | Editor plugin installed | --- ## 📦 ### 1️⃣ - **Godot 4.x** — [godotengine.org/download](https://godotengine.org/download) - **Node.js 18+** — [nodejs.org](https://nodejs.org/) - ### 2️⃣ **From npm (once published):** ```bash npm install -g godot-mcp-1969 ``` **From source:** ```bash git clone https://github.com/Reza2kn/godot-mcp.git cd godot-mcp npm install npm run build ``` ### 3️⃣ #### 🤖 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) `%APPDATA%\Claude\claude_desktop_config.json` (Windows) ```json { "mcpServers": { "godot": { "command": "node", "args": ["/absolute/path/to/godot-mcp/build/index.js"], "env": { "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot" } } } } ``` #### 🖱️ `.continue/config.json`: ```json { "mcpServers": [ { "name": "godot", "command": "node", "args": ["/absolute/path/to/godot-mcp/build/index.js"], "env": { "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot" } } ] } ``` #### 🦙 ```bash GODOT_PATH=/Applications/Godot.app/Contents/MacOS/Godot \ GODOT_MCP_DISCOVERY_MODE=true \ node /path/to/godot-mcp/build/index.js ``` ### 4️⃣ | | | |----------|-------------| | 🍎 macOS | `/Applications/Godot.app/Contents/MacOS/Godot` | | 🪟 Windows | `C:\Program Files\Godot\Godot_v4.x-stable_win64.exe` | | 🐧 Linux | `/usr/local/bin/godot` or `~/godot/godot` | --- ## 🎮 ### 🌱 ``` Tell your AI: *"Create a 2D platformer project at ~/Games/MyPlatformer with a player, a ground, and a camera"* ``` ### ⚡ ``` "Move the player to the center of the screen" → set_node_position_2d nodePath="Player" x=540 y=300 "Spawn 5 enemies at random positions" → spawn_node × 5 "Play the explosion sound and shake the camera" → play_audio_stream + write_camera_shake_3d_script ``` ### 🧠 ``` "Add inventory, save/load, and a quest system to my game" → write_inventory_system_script → res://scripts/inventory.gd → write_save_load_system_script → res://scripts/save_manager.gd → write_quest_manager_script → res://scripts/quest_manager.gd → set_project_autoload (×3) → registered as singletons ``` --- ## 🧪 ```bash # Gameplay systems write_platformer_player_script # Full gravity + jump + run write_top_down_shooter_script # 8-dir movement + shooting write_enemy_state_machine_script # idle/patrol/chase/attack AI write_vehicle_controller_script # VehicleBody3D car physics write_double_jump_script # Double-jump with coyote time write_wall_jump_script # Wall-jump CharacterBody2D write_grappling_hook_script # Physics grapple mechanic write_dash_ability_script # Dodge with cooldown # Systems & managers write_save_load_system_script # JSON save/load write_inventory_system_script # Stacking inventory + signals write_quest_manager_script # Progress tracking write_dialogue_system_script # Branching dialogue + choices write_audio_manager_script # Singleton pooled audio write_achievement_system_script # Achievement unlocking write_state_machine_base_script # Generic reusable state machine write_signal_bus_script # Global event bus autoload # UI components write_health_component_script # Reusable health node write_pause_menu_script # Pause + resume + quit write_status_bar_ui_script # Generic health/XP bar write_hotbar_ui_script # Hotbar item slots write_minimap_ui_script # Viewport-based minimap write_tooltip_system_script # Hover tooltips write_drag_drop_slot_script # Drag-and-drop item slots write_fps_counter_script # FPS overlay label # World & environment write_day_night_cycle_script # Time cycle with signals write_weather_system_script # Weather state machine write_procedural_dungeon_script # Procedural room generation write_chunk_loading_script # Chunk-based world loading write_fog_of_war_script # Vision masking # Physics & interaction write_explosion_script # Radius damage area write_water_buoyancy_script # Buoyancy force area write_conveyor_belt_script # Moving surface velocity write_ladder_script # Climbable ladder write_zipline_script # Zipline mover write_pressure_plate_script # Trigger plate write_door_script # Animated open/close door write_ragdoll_setup_script # Ragdoll physics helper # ... and 60+ more ``` --- ## 🖥️ ``` Ask your AI: "Install the Godot editor plugin for my project" AI calls: install_editor_plugin projectPath="/path/to/your/project" ``` Then in Godot Editor: **Project → Project Settings → Plugins → Enable "Godot MCP Editor"** You'll see an **Agent Control dock** appear. Now the AI can: | | | |------|-----------------| | `editor_select_node_by_path` | Highlights a node in the scene tree | | `get_editor_selected_nodes` | Reads whatever you currently have selected | | `editor_undo` / `editor_redo` | Undo/redo in the editor | | `editor_save_scene` | Saves the current scene | | `get_editor_filesystem_files` | Lists files in any project folder | | `get_editor_inspector_object` | Reads the object in the Inspector panel | --- ## 🤖 **Always use discovery mode with local/small models.** Models under 30B parameters struggle with 1,969 tool schemas. ```bash GODOT_MCP_DISCOVERY_MODE=true node build/index.js ``` Then prompt your model to start with: > *"Call godot_start_here first to understand how to use this MCP server"* The model will understand the system in one call and navigate everything through `godot_suggest` + `godot_call`. No context overflow. No hallucinated tool names. ### 🧪 | | | | |-------|---------|-------| | **Qwen2.5-Coder 14B+** | ⭐⭐⭐⭐⭐ | Best local option for game dev | | **DeepSeek-Coder-V2 16B** | ⭐⭐⭐⭐⭐ | Excellent multi-step reasoning | | **Llama 3.3 70B** | ⭐⭐⭐⭐ | Solid, needs good prompting | | **Mistral 22B** | ⭐⭐⭐ | Works for simple tasks | | **Llama 3.1 8B** | ⭐⭐ | Use discovery mode, keep prompts tight | --- ## 🎬 ### 🔥 **"AI builds a complete platformer from zero"** ⏱️ ~5 min clip ``` Start: empty folder End: running game with player, ground, camera, physics Tools used: ~12 in sequence ``` **"1,969 things an AI can do in Godot"** ⏱️ ~3 min clip ``` Call list_tool_categories → show the scope Pick one category, browse it, demo a tool live ``` **"Local model plays Godot with only 20 tools"** ⏱️ ~8 min clip ``` GODOT_MCP_DISCOVERY_MODE=true + Ollama Show progressive discovery in action Tiny model, huge capability ``` **"AI generates a complete RPG system"** ⏱️ ~10 min clip ``` write_inventory_system_script write_quest_manager_script write_dialogue_system_script write_save_load_system_script → 4 complete systems in 30 seconds ``` **"AI controls the running game in real-time"** ⏱️ ~5 min clip ``` run_project → game is live set_node_position_2d → player teleports spawn_node → enemy appears apply_impulse_to_rigid_body → physics explosion play_audio_stream → sound plays ``` ### 📋 ```bash # Clone and build (2 min setup) git clone https://github.com/Reza2kn/godot-mcp.git cd godot-mcp npm install && npm run build # For local model demos (clean 20-tool UI) GODOT_PATH=/path/to/godot \ GODOT_MCP_DISCOVERY_MODE=true \ node build/index.js # For Claude / full power demos GODOT_PATH=/path/to/godot \ node build/index.js ``` --- ## 📚 | | | |------|-------| | `"platformer"` | 11 steps: CharacterBody2D → CollisionShape → Script → Camera → Test | | `"fps"` | 11 steps: CharacterBody3D → Camera3D → Mouse look → World → Lighting | | `"top down"` | 9 steps: 8-direction movement → TileMap walls → Camera smoothing | | `"audio"` | Background music + SFX bus setup + runtime control | | `"ui"` | CanvasLayer → HBoxContainer → Label → ProgressBar → anchor to screen | | `"physics"` | Body type guide → collision shapes → forces vs impulses | | `"signals"` | Connect → emit → custom signals → one-shot connections | | `"animation"` | AnimatedSprite2D → SpriteFrames → AnimationPlayer → blend times | --- ## 🔧 | | | | |----------|---------|-------------| | `GODOT_PATH` | auto-detect | Full path to the Godot 4 executable | | `GODOT_MCP_DISCOVERY_MODE` | `false` | `true` = expose 20 tools only (best for local models) | | `GODOT_PROJECTS_DIR` | `~/GodotProjects` | Default directory for new projects | --- ## 🏗️ ``` src/ ├── index.ts ← MCP server (1,969 tools, ~50,000 lines) └── scripts/ ├── godot_operations.gd ← Headless GDScript (file & resource ops) ├── mcp_interaction_server.gd ← Runtime TCP server (port 9090, 1,000+ commands) └── editor_mcp_server.gd ← Editor plugin TCP server (port 9091) build/ ├── index.js ← Compiled MCP server ├── scripts/ ← GDScript files (copied at build time) └── godot-editor-plugin/ ← Packaged Godot editor plugin └── addons/godot_mcp_editor/ ``` --- ## 🙏 This project builds on [godot-mcp](https://github.com/tugcantopaloglu/godot-mcp) by [Tugcan Topaloglu](https://github.com/tugcantopaloglu) — the ~150-tool server whose architecture (TypeScript MCP server + headless GDScript ops + TCP runtime bridge) we took and pushed all the way to 1,969. The original spark for AI-controlled Godot came from [Solomon Elias (Coding-Solo)](https://github.com/Coding-Solo). Both deserve credit. 🙌 --- ## 📜 MIT — build games, make tutorials, ship products, teach students, run livestreams. Go wild. 🎮 --- <div align="center"> **1,969 . Built for AI. Zero BS.** [⭐ Star this repo](https://github.com/Reza2kn/godot-mcp) · [🐛 Issues](https://github.com/Reza2kn/godot-mcp/issues) · [💬 Discussions](https://github.com/Reza2kn/godot-mcp/discussions) </div>