Godot MCP

Implements the Model Context Protocol specification by registering discrete tools with the MCP server and routing incoming requests from AI assistants (Claude via Cline, Cursor) to appropriate handlers. The GodotServer class manages tool metadata, parameter schemas, and request dispatching through a centralized registry that normalizes camelCase/snake_case parameter conversion before execution.

Automatically discovers the Godot executable path on the system and validates project structure before executing operations. The system searches standard installation locations, checks for valid project.godot configuration files, and verifies Godot version compatibility. This prevents execution errors by failing fast when prerequisites are missing or misconfigured.

Detects the installed Godot version through CLI execution and validates feature availability (e.g., UID support in 4.4+). The system parses Godot's version output, compares against known feature requirements, and returns compatibility status. This enables the MCP server to gracefully degrade or fail fast when requested features are unavailable in the installed Godot version.

Normalizes parameter naming conventions between AI assistant conventions (camelCase) and Godot API conventions (snake_case) through automatic conversion in the GodotServer class. The system maintains parameter schemas for each tool, validates incoming parameters against schemas, and converts naming conventions before passing to GDScript or CLI execution. This eliminates manual parameter mapping and reduces integration friction.

Provides consistent error handling and response formatting across all MCP tools through centralized error handlers in the GodotServer class. The system catches exceptions from CLI execution and GDScript operations, formats errors with context (operation name, parameters, stderr output), and returns structured error responses following MCP specification. This enables AI assistants to understand failures and retry with corrected parameters.

Routes operations through two execution paths: direct CLI commands for simple operations (launching editor, getting version) and bundled GDScript for complex operations requiring deep Godot API access. This hybrid approach eliminates temporary file creation, centralizes operation logic in the MCP server, and provides consistent error handling across both execution paths through a unified operation executor.

Provides tools to create new scene files with specified root nodes and add nodes to existing scenes through GDScript execution. The system accepts scene paths, node types, and parent node references, then executes bundled GDScript that instantiates nodes, sets properties, and saves the scene file. This enables AI assistants to programmatically build game hierarchies without manual editor interaction.

Loads texture files into Sprite2D nodes through GDScript execution that sets the texture property and optionally configures sprite parameters (scale, offset, animation frames). The system accepts sprite node paths, texture file paths, and optional configuration parameters, then executes bundled GDScript that loads the texture resource and applies settings without requiring editor interaction.

Launches Godot projects in headless or editor mode and captures console output in real-time through CLI execution with output stream redirection. The system starts the project process, monitors stderr/stdout, and provides a get_debug_output tool to retrieve accumulated output. This enables AI assistants to test game logic, observe runtime behavior, and diagnose errors without manual console monitoring.

Stops running Godot project processes and performs cleanup through process termination signals. The system tracks active project processes, sends SIGTERM or equivalent signals, and verifies process termination. This ensures clean shutdown of game instances and prevents resource leaks when testing multiple project iterations.

Exports 3D scenes as MeshLibrary assets for use with GridMap nodes through GDScript execution. The system accepts a 3D scene path, extracts mesh and material data from nodes, and generates a .meshlib file that GridMap can reference. This enables AI assistants to convert 3D models into reusable tile assets for procedural level generation.

Saves scene modifications to disk through GDScript execution that calls Godot's scene save API. The system accepts a scene path and optional node modifications, executes bundled GDScript to persist changes, and returns save status with error details. This ensures that programmatic scene edits are preserved and available for subsequent operations or manual editing.

Manages unique identifiers (UIDs) for Godot resources to enable robust reference tracking across scene and asset files. The system provides get_uid to retrieve UIDs for specific resources and update_project_uids to refresh all UIDs in a project after file reorganization. This leverages Godot 4.4's UID system to maintain referential integrity when assets are moved or renamed.