Godot MCP server

This MCP server enables AI assistants to interact with the Godot game engine by launching the editor, running projects, capturing debug output, and controlling project execution through a standardized interface. This direct feedback loop helps AI assistants better understand and work with Godot projects.

Installation

Prerequisites

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

Setup Process

Clone the repository and build the MCP server:

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

Configuration

Configure with Cline

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",
        "get_godot_version",
        "list_projects",
        "get_project_info",
        "create_scene",
        "add_node",
        "load_sprite",
        "export_mesh_library",
        "save_scene",
        "get_uid",
        "update_project_uids"
      ]
    }
  }
}

Configure with Cursor

Via 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

Via Project-Specific Configuration:

Create a file at .cursor/mcp.json in your project directory with:

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

Environment Variables

Customize the server behavior with:

• GODOT_PATH: Path to the Godot executable (overrides automatic detection)
• DEBUG: Set to "true" to enable detailed server-side debug logging

Usage

Once configured, your AI assistant will automatically run the MCP server when needed. Here are example prompts you can use:

• "Launch the Godot editor for my project at /path/to/project"
• "Run my Godot project and show me any errors"
• "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"

Features

The Godot MCP server provides these capabilities:

• 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:
  • 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

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
  • MCP tools can only be run using the Agent chat profile (requires Cursor Pro or Business)
  • Use "Yolo Mode" to automatically run MCP tool requests

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.