Godot MCP Unified - AI + Godot Architecture

Documentation for my future self - Complete configuration for coding in natural language within Godot

Read in English

Global Architecture

                    +------------------+
                    |   Claude Code    |
                    |    (VS Code)     |
                    +--------+---------+
                             |
                             v
+----------------+  +--------+---------+  +------------------+
| Claude Desktop |->|                  |<-| ollmcp (Ollama)  |
|   (Anthropic)  |  | godot-mcp-unified|  | qwen2.5-coder:7b |
+----------------+  |   (ce serveur)   |  +------------------+
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
              v                             v
     +--------+---------+          +--------+---------+
     |  Godot CLI       |          |  Plugin WebSocket|
     |  (--headless)    |          |  (addons/godot_  |
     |  Fallback mode   |          |   mcp/) Port 6505|
     +------------------+          +------------------+
              |                             |
              +-------------+---------------+
                            |
                            v
                   +--------+---------+
                   |  Godot Engine    |
                   |    4.5.1         |
                   +------------------+

Communication with Godot

The server automatically detects if the plugin is connected and uses the optimal mode.

Related MCP server: Godot MCP Server

What this server allows you to do

Do EVERYTHING in Godot using natural language (83 tools + 20 resources + 20 prompts):

Installation (already done)

Installed Prerequisites

• Node.js (for the MCP server)

• Godot 4.5.1: C:\Dev\Godot_v4.5.1-stable_win64.exe\Godot_v4.5.1-stable_win64_console.exe

• uv (modern Python manager)

• ollmcp (Ollama <-> MCP bridge)

This server

cd C:\Dev\godot-mcp-unified
npm install
npm run build

Configuration

Claude Desktop (C:\Users\pierr\AppData\Roaming\Claude\claude_desktop_config.json)

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

VS Code / Claude Code (.vscode/mcp.json in your Godot project)

{
  "servers": {
    "godot": {
      "command": "node",
      "args": ["C:\\Dev\\godot-mcp-unified\\build\\index.js"],
      "env": {
        "GODOT_PATH": "C:\\Dev\\Godot_v4.5.1-stable_win64.exe\\Godot_v4.5.1-stable_win64_console.exe"
      }
    }
  }
}

Ollama (via ollmcp)

# Lancer le bridge
ollmcp --model qwen2.5-coder:7b C:\Dev\godot-mcp-unified\build\index.js

# Ou via ollama-gateway (port 3010)

Available Ollama Models

Note: The -chess models are NOT for playing chess but are custom assistants for developing chess-app with FFE system prompts.

API Reference (83 tools + 20 resources + 20 prompts)

Statistics

Primitives MCP:
  Tools:     83/83   ████████████████████ 100%
  Resources: 20/20   ████████████████████ 100%
  Prompts:   20/20   ████████████████████ 100%

Qualite:
  Tests:    3170+    ████████████████████ 100% pass (69 suites)
  Coverage:  85%     █████████████████░░░  85%

Bridge Plugin:
  Avec bridge:  47 outils (utilisent WebSocket si plugin actif)
  Sans bridge:  35 outils (CLI/file I/O uniquement)

Project Management (14 tools)

• launch_editor - Open Godot editor

• run_project - Run a project

• stop_project - Stop the project

• list_projects - List projects in a folder

• get_project_info - Info about a project

• get_godot_version - Godot version

• get_project_settings - Read project settings

• set_project_setting - Modify a setting

• manage_input_actions - Manage input actions

• manage_autoloads - Manage autoloads

• validate_project - Validate project structure

• convert_project - Convert Godot 3 project to 4

• validate_conversion - Validate a conversion

• generate_docs - Generate GDScript documentation

Scene Management (15 tools)

• create_scene - Create a new scene

• add_node - Add a node

• edit_node - Modify node properties

• remove_node - Remove a node

• rename_node - Rename a node

• move_node - Move a node (reparent)

• duplicate_node - Duplicate a node

• load_sprite - Load a texture

• save_scene - Save a scene

• instance_scene - Instance a scene

• list_scenes - List scenes

• get_node_tree - Get scene tree

• connect_signal - Connect a signal

• manage_groups - Manage node groups

• export_mesh_library - Export as MeshLibrary

GDScript Scripts (7 tools)

• list_scripts - List all .gd files in the project

• read_script - Read script content

• write_script - Create/modify a script

• delete_script - Delete a script

• attach_script - Attach script to a node

• detach_script - Detach script from a node

• get_script_errors - Compilation errors

Animation (7 tools)

• create_animation_player - Create AnimationPlayer

• add_animation - Add animation

• add_animation_track - Add track (value, position, rotation, etc.)

• set_keyframe - Set keyframe with transition/easing

• create_animation_tree - Create AnimationTree

• setup_state_machine - Configure state machine

• blend_animations - Configure animation blending

Physics (3 tools)

• create_collision_shape - Create CollisionShape2D/3D

• setup_rigidbody - Configure RigidBody (mass, gravity)

• configure_physics_layers - Name 2D/3D physics layers

TileMap (5 tools)

• create_tileset - Create TileSet with tile size

• create_tilemap_layer - Create TileMapLayer

• set_tile - Place a tile

• paint_tiles - Paint tiles in batch

• import_ldtk_level - Import LDtk level

Audio (3 tools)

• create_audio_bus - Create audio bus

• setup_audio_player - Configure AudioStreamPlayer

• add_audio_effect - Add effect (reverb, delay, eq)

Shader (2 tools)

• create_shader - Create .gdshader file

• create_shader_material - Create ShaderMaterial

Navigation (2 tools)

• create_navigation_region - Create NavigationRegion2D/3D

• bake_navigation_mesh - Bake navmesh

Particles (2 tools)

• create_gpu_particles - Create GPUParticles2D/3D

• create_particle_material - Create ParticleProcessMaterial

UI (2 tools)

• create_ui_container - Create Container (VBox, HBox, Grid, etc.)

• create_control - Create Control (Button, Label, etc.)

Lighting (3 tools)

• create_light - Create Light2D/3D (Directional, Omni, Spot)

• setup_environment - Configure Environment (fog, glow, SSAO)

• setup_lightmapper - Configure LightmapGI and baking

Assets (3 tools)

• list_assets - List assets (images, audio, models)

• import_asset - Import external file

• reimport_assets - Force reimport

Export (3 tools)

• export_project - Export project

• export_pack - Export PCK only

• list_export_presets - List export presets

Batch Operations (1 tool)

• batch_operations - Execute multiple MCP tools in sequence

Debug (5 tools)

• get_debug_output - Retrieve console output

• start_debug_stream - Start debug WebSocket server

• stop_debug_stream - Stop WebSocket server

• get_debug_stream_status - Server status

• take_screenshot - Capture a screenshot

UID (Godot 4.4+) (2 tools)

• get_uid - Get file UID

• update_project_uids - Update references

System (2 tools)

• system_health - System health check

• get_godot_version - Godot version

Usage Examples

Create a player character

"Cree une scene Player.tscn avec un CharacterBody2D comme root,
ajoute un Sprite2D nomme 'Sprite' et un CollisionShape2D nomme 'Collision'"

Debug a project

"Lance mon projet Godot et montre-moi les erreurs dans la console"

Modify an existing scene

"Dans la scene Player.tscn, change la position du Sprite a (100, 50)
et sa scale a 2x"

Godot Project Structure

C:\Dev\
├── jdvlh-godot-client\     <- Projet principal (pas de remote git configure!)
│   ├── project.godot
│   ├── .vscode\mcp.json    <- Config MCP pour ce projet
│   └── addons\godot_mcp\   <- Plugin MCP copie
│
├── jdvlh-godot\            <- Projet vide (a garder pour tests)
│
└── GodotDynamicDialog\     <- Fork de dynamic-dialog

Code Origin

This server unifies the features of 3 open-source projects:

Note: GDAI MCP exists but is paid ($19).

Machine Specs

• CPU: Ryzen 5 5600H

• RAM: 16 GB

• GPU: AMD Radeon (integrated) - no CUDA

• Optimal quantization: Q4_K_M (quality/performance sweet spot)

Troubleshooting

Server won't start

cd C:\Dev\godot-mcp-unified
npm run build

Godot not found

Verify that GODOT_PATH points to the correct executable (console version to see logs).

Claude Desktop doesn't see the tools

Restart Claude Desktop after modifying the config.

Useful Commands

# Rebuild le serveur
cd C:\Dev\godot-mcp-unified && npm run build

# Tester avec l'inspecteur MCP
npm run inspector

# Lister les modeles Ollama
ollama list

# Supprimer un modele Ollama
ollama rm nom_modele

TODO

• [ ] Configure git remote for jdvlh-godot-client

• [ ] Clean up redundant Ollama models (qwen2.5, gemma2, llama3.2, deepseek-coder-v2)

• [ ] Test full integration with a new project

Last updated: February 11, 2026 godot-mcp-unified v0.9.0 - 83 tools + 20 resources + 20 prompts Coverage: 85% | Tests: 3170+ (69 suites) | ISO 25010/29119/5055/27001 compliant