(((((((             (((((((                          
                        (((((((((((           (((((((((((                      
                        (((((((((((((       (((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
                        (((((((((((((((((((((((((((((((((                       
         (((((      (((((((((((((((((((((((((((((((((((((((((      (((((        
       (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((      
     ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
    ((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((    
      (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((     
        (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((       
         (((((((((((@@@@@@@(((((((((((((((((((((((((((@@@@@@@(((((((((((        
         (((((((((@@@@,,,,,@@@(((((((((((((((((((((@@@,,,,,@@@@(((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         ((((((((@@@,,,,,,,,,@@(((((((@@@@@(((((((@@,,,,,,,,,@@@((((((((        
         (((((((((@@@,,,,,,,@@((((((((@@@@@((((((((@@,,,,,,,@@@(((((((((        
         ((((((((((((@@@@@@(((((((((((@@@@@(((((((((((@@@@@@((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((        
         @@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@((((((((((((@@@@@@@@@@@@@        
         ((((((((( @@@(((((((((((@@(((((((((((@@(((((((((((@@@ (((((((((        
         (((((((((( @@((((((((((@@@(((((((((((@@@((((((((((@@ ((((((((((        
          (((((((((((@@@@@@@@@@@@@@(((((((((((@@@@@@@@@@@@@@(((((((((((         
           (((((((((((((((((((((((((((((((((((((((((((((((((((((((((((          
              (((((((((((((((((((((((((((((((((((((((((((((((((((((             
                 (((((((((((((((((((((((((((((((((((((((((((((((                
                        (((((((((((((((((((((((((((((((((                       
                                                                                

                          /$$      /$$  /$$$$$$  /$$$$$$$ 
                         | $$$    /$$$ /$$__  $$| $$__  $$
                         | $$$$  /$$$$| $$  \__/| $$  \ $$
                         | $$ $$/$$ $$| $$      | $$$$$$$/
                         | $$  $$$| $$| $$      | $$____/ 
                         | $$\  $ | $$| $$    $$| $$      
                         | $$ \/  | $$|  $$$$$$/| $$      
                         |__/     |__/ \______/ |__/       

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

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.

• Launch Godot Editor: Open the Godot editor for a specific project
• Run Godot Projects: Execute Godot projects in debug mode
  • Multi-Instance Support: Run multiple Godot instances simultaneously (e.g., dedicated server + multiple clients)
  • Batch Launch: Launch multiple instances in a single call with run_multiple_projects
  • Staggered Startup: Use delayMs to stagger instance launches (e.g., start server before clients)
  • Custom Command-Line Arguments: Pass additional arguments to Godot (e.g., --server, --headless, profile=X, port=Y)
  • Instance Management: Track and manage multiple running instances with unique IDs
  • Bounded Output Buffers: Automatic memory management for long-running instances (keeps last 1000 lines)
  • Auto-Cleanup: Stale exited processes are automatically cleaned up after 10 minutes
• Capture Debug Output: Retrieve console output and error messages for specific instances or all instances
• Control Execution: Start and stop Godot projects programmatically
  • Stop individual instances, multiple specific instances, or all at once
• List Running Processes: View all currently running Godot instances and their status
• 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:
  • Create new scenes with specified root node types
  • Add nodes to existing scenes with customizable properties
  • Load sprites and textures into Sprite2D nodes
  • Export 3D scenes as MeshLibrary resources for GridMap
  • Save scenes with options for creating variants
• UID Management (for Godot 4.4+):
  • Get UID for specific files
  • Update UID references by resaving resources

• Godot Engine installed on your system
• Node.js and npm
• An AI assistant that supports MCP (Cline, Cursor, etc.)

First, clone the repository and install dependencies:

git clone https://github.com/Coding-Solo/godot-mcp.git
cd godot-mcp
npm install

To build the MCP server for CLI use:

npm run build

To build the MCPB extension for Claude Desktop:

npm run build:mcpb

After building, double-click the generated .mcpb file in the build directory to install it in Claude Desktop. In the Config menu, set the path to your Godot executable. You can skip the rest of the configuration steps below.

Add to your Cline MCP settings file (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/absolute/path/to/godot-mcp/build/index.js"],
      "env": {
        "DEBUG": "true"                  // Optional: Enable detailed logging
      },
      "disabled": false,
      "autoApprove": [
        "launch_editor",
        "run_project",
        "get_debug_output",
        "stop_project",
        "list_processes",
        "run_multiple_projects",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

Using the Cursor UI:

1. Go to Cursor Settings > Features > MCP
2. Click on the + Add New MCP Server button
3. Fill out the form:
   • Name: godot (or any name you prefer)
   • Type: command
   • Command: node /absolute/path/to/godot-mcp/build/index.js
4. Click "Add"
5. 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:

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

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

Once configured, your AI assistant will automatically run the MCP server when needed. You can use prompts like:

"Launch the Godot editor for my project at /path/to/project"

"Run my Godot project and show me any errors"

"Run my Godot project as a dedicated server on port 8080 in headless mode"

"Launch a client instance with custom profile connecting to localhost:8080"

"Launch a server and two clients for my multiplayer game, with the server starting first"

"List all currently running Godot instances"

"Stop all client instances but keep the server running"

"Get debug output for the server instance"

"Stop the client instance with ID 'client1'"

"Get information about my Godot project structure"

"Analyze my Godot project structure and suggest improvements"

"Help me debug this error in my Godot project: [paste error]"

"Write a GDScript for a character controller with double jump and wall sliding"

"Create a new scene with a Player node in my Godot project"

"Add a Sprite2D node to my player scene and load the character texture"

"Export my 3D models as a MeshLibrary for use with GridMap"

"Create a UI scene with buttons and labels for my game's main menu"

"Get the UID for a specific script file in my Godot 4.4 project"

"Update UID references in my Godot project after upgrading to 4.4"

The Godot MCP server uses a bundled GDScript approach for complex operations:

1. Direct Commands: Simple operations like launching the editor or getting project info use Godot's built-in CLI commands directly.
2. 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.

The MCP server supports running multiple Godot instances simultaneously, which is essential for multiplayer game development and testing:

• Instance IDs: Each running instance can be assigned a unique identifier (e.g., "server", "client1", "client2") or use auto-generated IDs
• Command-Line Arguments: Pass custom arguments to each instance (e.g., --server, --headless, profile=X, port=Y)
• Batch Launch: Use run_multiple_projects to launch multiple instances in a single tool call
• Staggered Startup: Use delayMs parameter to delay instance launches (e.g., start server 2 seconds before clients)
• Instance Management:
  • Use list_processes to see all running instances and their status
  • Use get_debug_output with an instanceId to get output for a specific instance
  • Use stop_project with instanceId (single) or instanceIds (array) to stop specific instances, or without parameters to stop all

Example Workflow for Multiplayer Development:

Option 1: Single Tool Call (Recommended)

Use run_multiple_projects to launch everything at once with staggered delays:

{
  "instances": [
    {
      "projectPath": "/path/to/project",
      "instanceId": "server",
      "args": ["--", "--server", "port=8080", "--headless"],
      "delayMs": 0
    },
    {
      "projectPath": "/path/to/project",
      "instanceId": "client1",
      "args": ["--", "profile=player1", "ip=127.0.0.1", "port=8080"],
      "delayMs": 2000
    },
    {
      "projectPath": "/path/to/project",
      "instanceId": "client2",
      "args": ["--", "profile=player2", "ip=127.0.0.1", "port=8080"],
      "delayMs": 2000
    }
  ]
}

Option 2: Individual Tool Calls

1. Launch dedicated server: run_project with instanceId: "server" and args: ["--", "--server", "port=8080", "--headless"]
2. Launch client instances: run_project with instanceId: "client1" and args: ["--", "profile=player1", "ip=127.0.0.1", "port=8080"]

Managing Instances:

• Monitor instances: Use list_processes to see all running instances
• Get specific output: Use get_debug_output with instanceId: "server" to see server logs
• Stop specific instances: Use stop_project with instanceIds: ["client1", "client2"] to stop multiple clients
• Stop all instances: Use stop_project without parameters

• 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

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