Godot MCP

by bradypp

526 downloads Not rated yet MIT license

GitHub

Other

About

A Model Context Protocol (MCP) server for interacting with the Godot game engine.

Details

License: MIT license

Explore

- Launch Godot editor and run projects with debug output capture
- Create, modify, and manage Godot scenes and nodes
- Load textures into Sprite2D nodes and export MeshLibrary resources
- Get Godot version, project info, and list projects in directories
- Support for Godot 4.4+ UID management (get and update UIDs)
- Optional read-only mode for safe project analysis
- Zero-config automatic Godot detection with manual override

npm install

Add to your Cline MCP settings file:

``json { "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" ] } } }



1. Open Cursor Settings → Features → MCP

2. Click + Add New MCP Server

3. Configure:

   - Name: godot

   - Type: command

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

4. Click Add and refresh the server list
Create .cursor/mcp.json in your project root:

json

{

  "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"

      }

    }

  }

}



| 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            |
If you encounter issues not covered here:



1. Check debug logs with DEBUG=true`

2. Search existing issues on GitHub

3. Create a detailed issue report with:

   - Operating system and version

   - Node.js and Godot versions

   - Complete error messages

   - Configuration used

   - Steps to reproduce

bash

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

``typescript 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.

![](https://modelcontextprotocol.io/introduction)

![](https://nodejs.org/en/download/) ![](https://www.typescriptlang.org/) ![](https://github.com/bradypp/godot-mcp/commits/main) ![](https://github.com/bradypp/godot-mcp/stargazers) ![](https://github.com/bradypp/godot-mcp/network/members) ![](https://opensource.org/licenses/MIT) A comprehensive Model Context Protocol (MCP) server for seamless AI assistant integration with the Godot game engine.

- What is Godot MCP? - Features - Requirements - Installation - Configuration - API Reference - Project Architecture - Usage Examples - Read-Only Mode - Troubleshooting - FAQ - Contributing - License

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: 1. Validates the request and project structure 2. Executes the appropriate Godot operations 3. Returns detailed success/error feedback 4. 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

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.