godot-mcp

Godot MCP Server

Connect Claude Code to Godot 4.6+ game engine via Model Context Protocol (MCP).

Architecture

┌─────────────────────────────────────────────────────────┐
│              Claude Code                                 │
└─────────────────────┬───────────────────────────────────┘
                      │ MCP Protocol (stdio)
┌─────────────────────▼───────────────────────────────────┐
│              MCP Server (TypeScript)                     │
│  - @modelcontextprotocol/sdk                            │
│  - Tool definitions and request routing                  │
│  - WebSocket client (connects to Godot Plugin)           │
└─────────────────────┬───────────────────────────────────┘
                      │ WebSocket (localhost:6505)
┌─────────────────────▼───────────────────────────────────┐
│           Godot Editor Plugin (GDScript)                 │
│  - addons/godot_mcp/                                     │
│  - WebSocket server                                      │
│  - EditorPlugin integration                              │
│  - Direct EditorInterface and SceneTree access           │
└─────────────────────────────────────────────────────────┘

Features

Project Operations

• Get project information and settings
• List all resources (scenes, scripts, textures, audio, etc.)

Scene Operations

• List all scenes in the project
• Read scene structure (node tree, properties)
• Create new scenes
• Save and open scenes

Script Operations

• List all GDScript files
• Read script content and metadata (functions, signals, properties)
• Create and modify scripts
• Add functions, signals, and variables to existing scripts

Node Operations

• Add nodes to scenes
• Instance scenes as child nodes
• Duplicate existing nodes
• Modify node properties
• Delete nodes
• Rename and reparent nodes
• Connect signals
• Attach scripts to nodes

Runtime Control

• Run the project or specific scenes
• Stop running projects
• Get runtime status
• Reload scenes

Installation

Claude Code Plugin (Recommended)

# Add marketplace
/plugin marketplace add signalcompose/godot-mcp

# Install the plugin
/plugin install godot-mcp@signalcompose

After installing the plugin, the MCP server will be built automatically during installation.

If you need to rebuild manually:

cd ~/.claude/plugins/marketplaces/godot-mcp/mcp-server
npm run build

Then use the setup command to install the Godot plugin:

/godot-mcp:setup

This will copy the Godot Editor plugin to your project's addons/ folder.

📖 New to Godot MCP? Check out the Getting Started Guide (日本語) for a complete step-by-step walkthrough.

Manual Installation

MCP Server

Clone the repository and build the server:

# Clone the repository
git clone https://github.com/signalcompose/godot-mcp.git
cd godot-mcp/plugins/godot-mcp/mcp-server

# Install dependencies and build
npm install
npm run build

Configure Claude Code to use the local build by adding to your MCP settings:

{
  "godot-mcp": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/godot-mcp/plugins/godot-mcp/mcp-server/dist/index.js"],
    "env": {
      "GODOT_MCP_PORT": "6505"
    }
  }
}

Godot Plugin

The Godot Editor plugin must be installed separately. Choose one method:

Option A: Using /godot-mcp:setup command (Recommended)

If you have the Claude Code plugin installed, run:

/godot-mcp:setup

Option B: From GitHub

Download the godot-plugin/addons/godot_mcp/ folder from the repository and copy it to your Godot project's addons/ folder.

Enable the Plugin

1. Open your project in Godot Editor
2. Go to Project > Project Settings > Plugins
3. Find "Godot MCP" and enable it

Configuration

Environment Variables

Variable	Default	Description
GODOT_MCP_PORT	6505	WebSocket port for communication

Claude Code Settings

The plugin's .mcp.json is pre-configured to use the local build:

{
  "godot-mcp": {
    "type": "stdio",
    "command": "node",
    "args": ["mcp-server/dist/index.js"],
    "env": {
      "GODOT_MCP_PORT": "6505"
    }
  }
}

Note: The plugin uses a local build with automatic compilation via the prepare script. No npm publication required.

Usage

Getting Started: Setup Guide | セットアップガイド

Detailed Guide: User Guide | ユーザーガイド

Slash Commands

• /godot-mcp:setup - Install Godot plugin to your project
• /godot-mcp:status - Check connection status
• /godot-mcp:debug - Run diagnostics

Natural Language Examples