Godot MCP
Note: Code block was split into 2 parts due to size limits.
A Model Context Protocol (MCP) server for interacting with the Godot game engine.
Introduction
Godot MCP enables AI assistants to launch the Godot editor, run projects, capture debug output, and control project execution - all through a standardized interface.
This direct feedback loop helps AI assistants like Claude understand what works and what doesn't in real Godot projects, leading to better code generation and debugging assistance.
Features
- Launch Godot Editor: Open the Godot editor for a specific project
- Run Godot Projects: Execute Godot projects in debug mode
- Capture Debug Output: Retrieve console output and error messages
- Control Execution: Start and stop Godot projects programmatically
- Get Godot Version: Retrieve the installed Godot version
- List Godot Projects: Find Godot projects in a specified directory
- Project Analysis: Get detailed information about project structure
- Scene Management:
- UID Management (for Godot 4.4+):
Requirements
- Godot Engine installed on your system
- Node.js and npm
- An AI assistant that supports MCP (Cline, Cursor, etc.)
Installation and Configuration
Step 1: Install and Build
First, clone the repository and build the MCP server:
Step 2: Configure with Your AI Assistant
Option A: Configure with Cline
Add to your Cline MCP settings file (
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):Option B: Configure with Cursor
Using the Cursor UI:
- Go to Cursor Settings > Features > MCP
- Click on the + Add New MCP Server button
- Fill out the form:
- Click "Add"
- You may need to press the refresh button in the top right corner of the MCP server card to populate the tool list
Using Project-Specific Configuration:
Create a file at
.cursor/mcp.json in your project directory with the following content:Step 3: Optional Environment Variables
You can customize the server behavior with these environment variables:
GODOT_PATH: Path to the Godot executable (overrides automatic detection)
DEBUG: Set to "true" to enable detailed server-side debug logging
Example Prompts
Once configured, your AI assistant will automatically run the MCP server when needed. You can use prompts like:
Implementation Details
Architecture
The Godot MCP server uses a bundled GDScript approach for complex operations:
- Direct Commands: Simple operations like launching the editor or getting project info use Godot's built-in CLI commands directly.
- Bundled Operations Script: Complex operations like creating scenes or adding nodes use a single, comprehensive GDScript file (
godot_operations.gd) that handles all operations.
This architecture provides several benefits:
- No Temporary Files: Eliminates the need for temporary script files, keeping your system clean
- Simplified Codebase: Centralizes all Godot operations in one (somewhat) organized file
- Better Maintainability: Makes it easier to add new operations or modify existing ones
- Improved Error Handling: Provides consistent error reporting across all operations
- Reduced Overhead: Minimizes file I/O operations for better performance
The bundled script accepts operation type and parameters as JSON, allowing for flexible and dynamic operation execution without generating temporary files for each operation.
Troubleshooting
- Godot Not Found: Set the GODOT_PATH environment variable to your Godot executable
- Connection Issues: Ensure the server is running and restart your AI assistant
- Invalid Project Path: Ensure the path points to a directory containing a project.godot file
- Build Issues: Make sure all dependencies are installed by running
npm install
- For Cursor Specifically:
- Ensure the MCP server shows up and is enabled in Cursor settings (Settings > MCP)
- MCP tools can only be run using the Agent chat profile (Cursor Pro or Business subscription)
- Use "Yolo Mode" to automatically run MCP tool requests
License
This project is licensed under the MIT License - see the LICENSE file for details.
Godot MCP
Note: Code block was split into 2 parts due to size limits.
A Model Context Protocol (MCP) server for interacting with the Godot game engine.
Introduction
Godot MCP enables AI assistants to launch the Godot editor, run projects, capture debug output, and control project execution - all through a standardized interface.
This direct feedback loop helps AI assistants like Claude understand what works and what doesn't in real Godot projects, leading to better code generation and debugging assistance.
Features
- Launch Godot Editor: Open the Godot editor for a specific project
- Run Godot Projects: Execute Godot projects in debug mode
- Capture Debug Output: Retrieve console output and error messages
- Control Execution: Start and stop Godot projects programmatically
- Get Godot Version: Retrieve the installed Godot version
- List Godot Projects: Find Godot projects in a specified directory
- Project Analysis: Get detailed information about project structure
- Scene Management:
- UID Management (for Godot 4.4+):
Requirements
- Godot Engine installed on your system
- Node.js and npm
- An AI assistant that supports MCP (Cline, Cursor, etc.)
Installation and Configuration
Step 1: Install and Build
First, clone the repository and build the MCP server:
Step 2: Configure with Your AI Assistant
Option A: Configure with Cline
Add to your Cline MCP settings file (
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):Option B: Configure with Cursor
Using the Cursor UI:
- Go to Cursor Settings > Features > MCP
- Click on the + Add New MCP Server button
- Fill out the form:
- Click "Add"
- You may need to press the refresh button in the top right corner of the MCP server card to populate the tool list
Using Project-Specific Configuration:
Create a file at
.cursor/mcp.json in your project directory with the following content:Step 3: Optional Environment Variables
You can customize the server behavior with these environment variables:
GODOT_PATH: Path to the Godot executable (overrides automatic detection)
DEBUG: Set to "true" to enable detailed server-side debug logging
Example Prompts
Once configured, your AI assistant will automatically run the MCP server when needed. You can use prompts like:
Implementation Details
Architecture
The Godot MCP server uses a bundled GDScript approach for complex operations:
- Direct Commands: Simple operations like launching the editor or getting project info use Godot's built-in CLI commands directly.
- Bundled Operations Script: Complex operations like creating scenes or adding nodes use a single, comprehensive GDScript file (
godot_operations.gd) that handles all operations.
This architecture provides several benefits:
- No Temporary Files: Eliminates the need for temporary script files, keeping your system clean
- Simplified Codebase: Centralizes all Godot operations in one (somewhat) organized file
- Better Maintainability: Makes it easier to add new operations or modify existing ones
- Improved Error Handling: Provides consistent error reporting across all operations
- Reduced Overhead: Minimizes file I/O operations for better performance
The bundled script accepts operation type and parameters as JSON, allowing for flexible and dynamic operation execution without generating temporary files for each operation.
Troubleshooting
- Godot Not Found: Set the GODOT_PATH environment variable to your Godot executable
- Connection Issues: Ensure the server is running and restart your AI assistant
- Invalid Project Path: Ensure the path points to a directory containing a project.godot file
- Build Issues: Make sure all dependencies are installed by running
npm install
- For Cursor Specifically:
- Ensure the MCP server shows up and is enabled in Cursor settings (Settings > MCP)
- MCP tools can only be run using the Agent chat profile (Cursor Pro or Business subscription)
- Use "Yolo Mode" to automatically run MCP tool requests
License
This project is licensed under the MIT License - see the LICENSE file for details.