Godot MCP

A comprehensive Model Context Protocol (MCP) server for seamless AI assistant integration with the Godot game engine.

What is Godot MCP?

Godot MCP bridges the gap between AI assistants and the Godot game engine by providing a standardized Model Context Protocol interface. This powerful integration enables AI assistants like Claude, Cursor, and Cline to directly interact with Godot projects through a comprehensive set of tools.

Key Value Propositions

Direct Godot Integration: Launch editors, run projects, and capture debug output programmatically
Scene Management: Create, modify, and manage Godot scenes through AI commands
Real-time Feedback: AI assistants can see actual Godot output and errors for better assistance
Cross-platform Compatibility: Works seamlessly on Windows, macOS, and Linux
Secure Operations: Optional read-only mode for safe project analysis
Zero Configuration: Automatic Godot detection with manual override options

How It Works

The server acts as a middleware layer between your AI assistant and Godot, translating natural language commands into specific Godot operations. When you ask your AI to "create a player scene with a sprite," the MCP server:

Validates the request and project structure
Executes the appropriate Godot operations
Returns detailed success/error feedback
Enables the AI to understand and respond to the results

This creates a powerful feedback loop where AI assistants can learn from actual Godot behavior, leading to more accurate code generation and debugging assistance.

Features

Core Project Management

🚀 Launch Godot Editor: Open the Godot editor for specific projects
▶️ Run Godot Projects: Execute projects in debug mode with real-time output capture
🛑 Control Execution: Start and stop Godot projects programmatically
📊 Debug Output Capture: Retrieve comprehensive console output and error messages
ℹ️ System Information: Get installed Godot version and project metadata
📁 Project Discovery: Find and list Godot projects in specified directories

Advanced Scene Management

🎬 Create New Scenes: Generate scenes with specified root node types
➕ Add Nodes: Insert nodes into existing scenes with customizable properties
✏️ Edit Node Properties: Modify positions, scales, textures, and other node attributes
🗑️ Remove Nodes: Clean up scenes by removing unwanted nodes
🖼️ Load Sprites: Automatically load textures into Sprite2D nodes
🧱 Export MeshLibrary: Convert 3D scenes to MeshLibrary resources for GridMap
💾 Save Scene Variants: Create scene copies and manage scene versions

Godot 4.4+ UID Management

🔗 Get File UIDs: Retrieve unique identifiers for project resources
🔄 Update UID References: Maintain proper resource links during project upgrades

Security & Safety

🔒 Read-Only Mode: Restrict operations to analysis-only for secure environments
✅ Path Validation: Comprehensive project and file path verification
🛡️ Error Handling: Robust error reporting with actionable suggestions

Requirements

System Requirements

Godot Engine: Version 3.5+ or 4.0+ (latest stable recommended)
Node.js & npm

AI Assistant Compatibility

Cline & Roo Code: Full support with auto-approval configuration
~~Cursor & VS Code: Supports both UI and project-specific configuration~~

Claude Desktop: Compatible with MCP server integration

Other MCP-enabled tools: Any tool supporting the Model Context Protocol

Installation

Clone and Build

# Clone the repository git clone https://github.com/bradypp/godot-mcp.git cd godot-mcp # Install dependencies npm install # Build the project npm run build

Configuration

Option A: Cline Configuration

Add to your Cline MCP settings file:

{ "mcpServers": { "godot": { "command": "node", "args": ["/absolute/path/to/godot-mcp/build/index.js"], "env": { "DEBUG": "false", "READ_ONLY": "false", "GODOT_PATH": "/path/to/godot" }, "disabled": false, "autoApprove": [ "launch_editor", "run_project", "get_debug_output", "stop_project", "get_godot_version", "list_projects", "get_project_info", "create_scene", "add_node", "edit_node", "remove_node", "load_sprite", "export_mesh_library", "save_scene", "get_uid", "update_project_uids" ] } } }

Option B: Cursor Configuration

UI Configuration

Open Cursor Settings → Features → MCP

Click + Add New MCP Server

Configure:

Name: godot

Type: command

Command: node /absolute/path/to/godot-mcp/build/index.js

Click Add and refresh the server list

Project-Specific Configuration

Create .cursor/mcp.json in your project root:

{ "mcpServers": { "godot": { "command": "node", "args": ["/absolute/path/to/godot-mcp/build/index.js"], "env": { "DEBUG": "false", "GODOT_PATH": "/path/to/godot", "READ_ONLY_MODE": "false" } } } }

Environment Variables

Variable Description Default Example

GODOT_PATH Path to Godot executable Auto-detected /usr/bin/godot4

DEBUG Enable detailed logging false true

READ_ONLY_MODE Restrict to read-only operations false true

API Reference

System Tools

get_godot_version

Get the installed Godot version information.

Parameters: None

Example Response:

{ "version": "4.2.1.stable", "platform": "linux.x86_64" }

Project Tools

launch_editor

Launch the Godot editor for a specific project.

Parameters:

projectPath (string, required): Path to the Godot project directory

Example:

{ "projectPath": "/home/user/my-game" }

run_project

Execute a Godot project and capture output.

Parameters:

projectPath (string, required): Path to the Godot project directory

scene (string, optional): Specific scene to run

Example:

{ "projectPath": "/home/user/my-game", "scene": "scenes/MainMenu.tscn" }

list_projects

Find Godot projects in a specified directory.

Parameters:

directory (string, required): Directory to search for projects

recursive (boolean, optional): Whether to search recursively (default: false)

get_project_info

Retrieve detailed metadata about a Godot project.

Parameters:

projectPath (string, required): Path to the Godot project directory

Example Response:

{ "name": "My Awesome Game", "path": "/home/user/my-awesome-game", "godotVersion": "4.2.1.stable.official", "structure": { "scenes": 12, "scripts": 8, "assets": 45, "other": 3 } }

Scene Management Tools

create_scene

Create a new scene in a Godot project.

Parameters:

projectPath (string, required): Path to the Godot project directory

scenePath (string, required): Path for the new scene file (relative to project)

rootNodeType (string, optional): Type of the root node (default: "Node2D")

Example:

{ "projectPath": "/home/user/my-game", "scenePath": "scenes/Player.tscn", "rootNodeType": "CharacterBody2D" }

add_node

Add a node to an existing scene.

Parameters:

projectPath (string, required): Path to the Godot project directory

scenePath (string, required): Path to the scene file (relative to project)

nodeType (string, required): Type of node to add (e.g., "Sprite2D", "CollisionShape2D")

nodeName (string, required): Name for the new node

parentNodePath (string, optional): Path to parent node (defaults to root)

properties (object, optional): Additional properties to set

Example:

{ "projectPath": "/home/user/my-game", "scenePath": "scenes/Player.tscn", "nodeType": "Sprite2D", "nodeName": "PlayerSprite", "properties": { "position": { "x": 100, "y": 50 }, "scale": { "x": 2.0, "y": 2.0 } } }

edit_node

Edit properties of an existing node in a scene.

Parameters:

projectPath (string, required): Path to the Godot project directory

scenePath (string, required): Path to the scene file (relative to project)

nodePath (string, required): Path to the node to edit

properties (object, required): Properties to update

Example:

{ "projectPath": "/home/user/my-game", "scenePath": "scenes/Player.tscn", "nodePath": "PlayerSprite", "properties": { "position": { "x": 200, "y": 100 }, "modulate": { "r": 1.0, "g": 0.5, "b": 0.5, "a": 1.0 } } }

remove_node

Remove a node from a scene.

Parameters:

projectPath (string, required): Path to the Godot project directory

scenePath (string, required): Path to the scene file (relative to project)

nodePath (string, required): Path to the node to remove

load_sprite

Load a texture into a Sprite2D node.

Parameters:

projectPath (string, required): Path to the Godot project directory

scenePath (string, required): Path to the scene file (relative to project)

nodePath (string, required): Path to the Sprite2D node

texturePath (string, required): Path to the texture file (relative to project)

save_scene

Save a scene, optionally as a new variant.

Parameters:

projectPath (string, required): Path to the Godot project directory

scenePath (string, required): Path to the scene file (relative to project)

newPath (string, optional): New path to save as variant

Debug Tools

get_debug_output

Retrieve current debug output and errors from running projects.

Parameters: None

stop_project

Stop any currently running Godot project.

Parameters: None

UID Tools (Godot 4.4+)

get_uid

Get the UID for a specific file in a Godot project.

Parameters:

projectPath (string, required): Path to the Godot project directory

filePath (string, required): Path to the file (relative to project)

update_project_uids

Update UID references in a project by resaving resources.

Parameters:

projectPath (string, required): Path to the Godot project directory

Project Architecture

Core Components

The Godot MCP server follows a modular architecture designed for maintainability and extensibility:

src/ ├── config/ # Configuration management ├── core/ # Core functionality │ ├── GodotExecutor.ts # Godot command execution │ ├── PathManager.ts # Path detection and validation │ ├── ProcessManager.ts # Process lifecycle management │ └── ParameterNormalizer.ts # Input parameter handling ├── server/ # MCP server implementation │ ├── GodotMCPServer.ts # Main server class │ └── types.ts # Type definitions ├── tools/ # Tool implementations │ ├── BaseToolHandler.ts # Shared tool functionality │ ├── ToolRegistry.ts # Tool registration and filtering │ ├── debug/ # Debug-related tools │ ├── project/ # Project management tools │ ├── scene/ # Scene manipulation tools │ ├── system/ # System information tools │ └── uid/ # UID management tools ├── utils/ # Utility functions └── scripts/ # Godot operation scripts

Key Design Principles

Modular Tool System: Each tool is self-contained with its own definition and handler

Centralized Configuration: Environment variables and settings managed in one location

Robust Error Handling: Comprehensive error reporting with actionable suggestions

Security First: Read-only mode and input validation protect against misuse

Cross-platform Support: Platform-agnostic design with OS-specific handling where needed

Tool Registration System

Tools are registered in the ToolRegistry with metadata indicating their capabilities:

export interface ToolRegistration { definition: ToolDefinition; handler: (args: any) => Promise<ToolResponse>; readOnly: boolean; }

The registry automatically filters tools based on the current mode (read-only vs. full access) and provides a unified interface for tool discovery and execution.

Bundled Operations Architecture

Complex Godot operations use a centralized GDScript approach:

Single Script File: All operations consolidated in godot_operations.gd

JSON Parameter Passing: Operations receive structured parameters

No Temporary Files: Eliminates file system overhead and cleanup complexity

Consistent Error Handling: Standardized error reporting across all operations

This architecture provides better performance, maintainability, and reliability compared to generating temporary scripts for each operation.

Usage Examples

Basic Project Workflow

"Launch the Godot editor for my project at /path/to/my-game" "Run my Godot project and show me any errors" "Get information about my project structure and settings"

Scene Creation and Management

"Create a new Player scene with a CharacterBody2D root node" "Add a Sprite2D node called 'PlayerSprite' to my Player scene" "Load the character texture 'textures/player.png' into the PlayerSprite node" "Set the Player's position to (100, 50) and scale to 2x" "Create a CollisionShape2D node as a child of the Player root"

Advanced Workflows

"Create a complete UI scene with buttons for Start Game, Settings, and Quit" "Export my 3D level models as a MeshLibrary for use with GridMap" "Analyze my project structure and suggest performance improvements" "Debug this GDScript error and help me fix the character controller" "Create a save system scene with file I/O nodes and data management"

Read-Only Mode

Read-only mode provides a secure way to analyze Godot projects without making any modifications. This is ideal for CI/CD pipelines, code reviews, educational environments, and shared development scenarios.

Enabling Read-Only Mode

Set the READ_ONLY_MODE environment variable to "true":

{ "mcpServers": { "godot": { "command": "node", "args": ["/absolute/path/to/godot-mcp/build/index.js"], "env": { "READ_ONLY_MODE": "true" } } } }

Available vs. Restricted Tools

✅ Available in Read-Only Mode

System Tools:

get_godot_version: Get Godot version information

Project Tools:

launch_editor: Launch Godot editor

run_project: Run projects to analyze behavior

list_projects: Discover projects in directories

get_project_info: Retrieve project metadata

Debug Tools:

get_debug_output: Capture console output

stop_project: Stop running projects

UID Tools:

get_uid: Get file UIDs (Godot 4.4+)

❌ Restricted in Read-Only Mode

Scene Modification Tools:

create_scene: Create new scenes

add_node: Add nodes to scenes

edit_node: Modify node properties

remove_node: Remove nodes from scenes

load_sprite: Load textures into nodes

export_mesh_library: Export MeshLibrary resources

save_scene: Save scene modifications

UID Modification Tools:

update_project_uids: Update UID references

Use Cases

🔄 CI/CD Pipelines: Automated project analysis without risk of modification

👥 Code Reviews: Safe project inspection for team collaboration

📊 Documentation: Extract project information for automated documentation

🔍 Debugging: Analyze project behavior without modification risk

Troubleshooting

Common Issues and Solutions

Godot Not Found

Error: Could not find a valid Godot executable path

Solutions:

Set GODOT_PATH environment variable:

export GODOT_PATH="/path/to/godot" # or for Windows: set GODOT_PATH="C:\Program Files\Godot\godot.exe"

Verify Godot installation:

# Test if Godot is accessible godot --version # or try: godot4 --version

Common Godot paths:

Windows: C:\Program Files\Godot\godot.exe

macOS: /Applications/Godot.app/Contents/MacOS/Godot

Linux: /usr/bin/godot4 or /usr/local/bin/godot

Connection Issues

Error: MCP server not responding or tools not available

Solutions:

Restart your AI assistant after configuration changes

Check server logs by enabling debug mode: "DEBUG": "true"

Verify configuration path is absolute and correct

Test server manually:
node /path/to/godot-mcp/build/index.js

Invalid Project Path

Error: Invalid project path or project.godot not found

Solutions:

Ensure path contains project.godot:
ls /path/to/project/project.godot

Use absolute paths when possible

Check file permissions on the project directory

Build Issues

Error: Build fails or dependencies missing

Solutions:

Clean and rebuild:

npm run clean npm install npm run build

Clear npm cache:

npm cache clean --force

Getting Help

If you encounter issues not covered here:

Check debug logs with DEBUG=true

Search existing issues on GitHub

Create a detailed issue report with:

Operating system and version

Node.js and Godot versions

Complete error messages

Configuration used

Steps to reproduce

FAQ

General Questions

Q: What versions of Godot are supported? A: Godot 3.5+ and all Godot 4.x versions. Some features (like UID management) require Godot 4.4+.

Q: Can I use this with Godot 3.x projects? A: Yes, most features work with Godot 3.5+. Scene management and project operations are fully supported.

Q: Is this safe to use on production projects? A: Yes, especially with read-only mode enabled. The server includes comprehensive validation and error handling.

Technical Questions

Q: How does the server detect my Godot installation? A: The server checks common installation paths for each platform. You can override detection with the GODOT_PATH environment variable.

Q: Can I run multiple instances of the server? A: Yes, each instance operates independently. Useful for working with multiple projects simultaneously.

Q: What happens if Godot crashes during an operation? A: The server detects process failures and returns appropriate error messages with suggestions for resolution.

Q: Are temporary files created during operations? A: No, the server uses a bundled GDScript approach that avoids temporary file creation for better performance and security.

AI Assistant Integration

Q: Which AI assistants work with this server? A: Any AI assistant supporting the Model Context Protocol, including Cline, Roo Code, Cursor, VS Code, Claude Desktop, and others.

Q: Can I customize which tools are available? A: Yes, through the autoApprove configuration or by modifying the tool registry for custom builds.

Q: How do I know if the integration is working? A: The AI assistant should be able to list available tools and execute them. Enable debug mode to see detailed operation logs.

Development Questions

Q: Can I add custom tools to the server? A: Yes, the modular architecture makes it easy to add new tools. See CONTRIBUTING.md for development guidelines.

Q: How do I contribute to the project? A: Fork the repository, make your changes, and submit a pull request. Please follow the existing code style and include tests.

Q: Is the server extensible for other game engines? A: The MCP architecture is engine-agnostic, but this implementation is specifically designed for Godot. Similar servers could be created for other engines.

Contributing

We welcome contributions to improve Godot MCP! Please see our CONTRIBUTING.md guide for:

Development setup instructions

Code style guidelines

Testing procedures

Pull request process

Issue reporting guidelines

Quick Start for Contributors

# Fork and clone the repository git clone https://github.com/your-username/godot-mcp.git cd godot-mcp # Install dependencies npm install # Start development mode npm run dev # Run tests npm test # Build for production npm run build

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

This project was originally forked from Coding-Solo/godot-mcp.

Support

🐛 Bug Reports: GitHub Issues

💡 Feature Requests: GitHub Discussions

📖 Documentation: This README and inline code documentation

💬 Community: Join discussions about Godot MCP and AI-assisted development

Built with ❤️ for the Godot and AI development communities

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
scripts		scripts
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Variable	Description	Default	Example
`GODOT_PATH`	Path to Godot executable	Auto-detected	`/usr/bin/godot4`
`DEBUG`	Enable detailed logging	`false`	`true`
`READ_ONLY_MODE`	Restrict to read-only operations	`false`	`true`

License

bradypp/godot-mcp

Folders and files

Latest commit

History

Repository files navigation

Godot MCP

Table of Contents

What is Godot MCP?

Key Value Propositions

How It Works

Features

Core Project Management

Advanced Scene Management

Godot 4.4+ UID Management

Security & Safety

Requirements

System Requirements

AI Assistant Compatibility

Installation

Clone and Build

Configuration

Option A: Cline Configuration

Option B: Cursor Configuration

UI Configuration

Project-Specific Configuration

Environment Variables

API Reference

System Tools

get_godot_version

Project Tools

launch_editor

run_project

list_projects

get_project_info

Scene Management Tools

create_scene

add_node

edit_node

remove_node

load_sprite

save_scene

Debug Tools

get_debug_output

stop_project

UID Tools (Godot 4.4+)

get_uid

update_project_uids

Project Architecture

Core Components

Key Design Principles

Tool Registration System

Bundled Operations Architecture

Usage Examples

Basic Project Workflow

Scene Creation and Management

Advanced Workflows

Read-Only Mode

Enabling Read-Only Mode

Available vs. Restricted Tools

✅ Available in Read-Only Mode

❌ Restricted in Read-Only Mode

Use Cases

Troubleshooting

Common Issues and Solutions

Godot Not Found

Connection Issues

Invalid Project Path

Build Issues

Getting Help

FAQ

General Questions

Technical Questions

AI Assistant Integration

Development Questions

Contributing

Quick Start for Contributors

License

Credits

Support

`get_godot_version`

`launch_editor`

`run_project`

`list_projects`

`get_project_info`

`create_scene`

`add_node`

`edit_node`

`remove_node`

`load_sprite`

`save_scene`

`get_debug_output`

`stop_project`

`get_uid`

`update_project_uids`

Packages