Godot Script Integration MCP server

This plugin allows AI assistants to interact with your Godot projects through the Model Context Protocol (MCP). Through natural language commands, Claude can access and modify scripts, scenes, nodes, and resources, enabling powerful code assistance and project management capabilities.

Installation

Prerequisites

• Godot Engine
• Node.js
• Claude Desktop

Setting Up the MCP Server

1. Clone the repository:

   git clone https://github.com/ee0pdt/godot-mcp.git
   cd godot-mcp
   

2. Install and build the server:

   cd server
   npm install
   npm run build
   cd ..
   

Configuring Claude Desktop

1. Edit or create the Claude Desktop configuration file:

   # For macOS
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. Add the following configuration:

   {
     "mcpServers": {
       "godot-mcp": {
         "command": "node",
         "args": [
           "PATH_TO_YOUR_PROJECT/server/dist/index.js"
         ],
         "env": {
           "MCP_TRANSPORT": "stdio"
         }
       }
     }
   }
   

   Be sure to replace PATH_TO_YOUR_PROJECT with the absolute path to your cloned repository.

3. Restart Claude Desktop

Opening the Example Project

1. Launch Godot Engine
2. Select "Import" and navigate to the cloned repository
3. Open the project.godot file
4. The MCP plugin is already enabled in this example project

Using the MCP Server

After setup, you can interact with your Godot project from Claude using natural language commands.

Basic Command Structure

To invoke MCP commands in Claude, use the following syntax:

@mcp godot-mcp COMMAND PARAMETERS

Essential Commands

Reading Files

To read the current script:

@mcp godot-mcp read godot://script/current

To read the current scene:

@mcp godot-mcp read godot://scene/current

To get project information:

@mcp godot-mcp read godot://project/info

Working with Nodes and Scenes

To get the scene tree structure:

@mcp godot-mcp run get-scene-tree

To create a new node:

@mcp godot-mcp run create-node

Example Tasks

Here are some natural language tasks you can ask Claude to perform:

• "Create a main menu with play, options, and quit buttons"
• "Add collision detection to the player character"
• "Implement a day/night cycle system"
• "Refactor this code to use signals instead of direct references"
• "Debug why my player character falls through the floor sometimes"

Sample Workflow

Here's an example of how you might use Claude with MCP:

1. Ask Claude to review your current script:

   @mcp godot-mcp read godot://script/current
   
   I need help optimizing my player movement code. Can you suggest improvements?
   

2. Request scene modification:

   @mcp godot-mcp run get-scene-tree
   
   Add a cube in the middle of the scene and then make a camera that is looking at the cube.
   

Troubleshooting

Connection Issues

• Ensure the plugin is enabled in Godot's Project Settings
• Check the Godot console for error messages
• Verify that paths in your Claude Desktop config are correct and absolute

Plugin Not Working

• Reload your Godot project after configuration changes
• Check for error messages in the Godot console
• Restart Claude Desktop after configuration changes

Adding to Your Own Project

To use the MCP plugin in your existing Godot project:

1. Copy the addons/godot_mcp folder to your project's addons directory
2. Open your project in Godot
3. Go to Project > Project Settings > Plugins
4. Enable the "Godot MCP" plugin

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.