Godot MCP Server (GMS)

A basic Model Context Protocol (MCP) server for the Godot game engine that enables AI assistants to interact with and manipulate Godot projects. This server, in general, uses the Godot command line to work with projects, so no Godot plugins are needed.

Table of Contents

Overview
Setup
Usage
Available Tools
Architecture
How It Works
Development
Example using Claude Desktop - Mac
License

Overview

The GMS provides a bridge between AI assistants (like Claude) and the Godot game engine. It allows AI models to:

Create and manage Godot projects
Launch the Godot editor
Run Godot projects
Manipulate scenes and nodes
Read and write files

This server implements the Model Context Protocol (MCP), which standardizes how AI assistants interact with external tools and services.

Setup

Prerequisites

Node.js (v14 or higher)
Godot Engine (v4.x recommended)

Installation

Clone this repository:

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

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Configuration

The server will automatically try to locate your Godot command line executable. If it can't find it, you can set the GODOT_PATH environment variable to the path of your Godot executable:

export GODOT_PATH=/path/to/your/godot

On different platforms, the server looks for Godot in these default locations:

macOS:
- /Applications/Godot.app/Contents/MacOS/Godot
- /Applications/Godot_4.app/Contents/MacOS/Godot
- /Applications/Godot_4.2.app/Contents/MacOS/Godot
Linux:
- /usr/bin/godot
- /usr/local/bin/godot
Windows:
- C:\Program Files\Godot\Godot.exe
- C:\Program Files (x86)\Godot\Godot.exe

Usage

Starting the Server

npm start

Or in development mode:

npm run dev

Using with MCP Inspector

You can test the server with the MCP Inspector:

npm run inspector

Using with Claude Desktop

You can integrate the GMS with Claude Desktop by adding it to the Claude Desktop configuration:

Locate the Claude Desktop configuration file:
- Generally on macOS: /Users/{username}/Library/Application Support/Claude/claude_desktop_config.json
Add the following configuration to the file:

{
  "mcpServers": {
    "godot-mcp": {
      "command": "node",
      "args": ["{full path to mcp}/godot-mcp-server/build/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Notes:

If the configuration file already contains an mcpServers object, add the godot-mcp entry to the existing object.
Replace {full path to mcp} with the actual path to where you cloned the repository.
You may need to use the complete path to the node executable if it's not in your system PATH.

Available Tools

The GMS provides the following tools:

Godot Tools

godot_version: Get the installed Godot version
launch_editor: Launch the Godot editor for a project
list_projects: List Godot projects in a directory
create_project: Create a new Godot project (3D, 2D, or empty)
run_project: Run a Godot project
stop_project: Stop a running project
get_debug_output: Get debug output from a running project
get_scene_tree: Get the scene tree from a project
create_scene: Create a new scene in a project
add_node: Add a node to a scene

File Tools

write_file: Write content to a file
read_file: Read content from a file

Architecture

The GMS is built with a modular architecture:

MCP Server Core: Uses the @modelcontextprotocol/sdk to create a server that communicates with AI assistants.
Tools Registration: Tools are registered with the MCP server to expose functionality to AI assistants.
Godot Integration: The server interacts with Godot in three main ways:
- Commands: Direct execution of Godot commands via command-line interface
- Operations: Complex operations executed through GDScript
- Utilities: Helper functions for finding Godot, running commands, etc.
File Operations: Basic file I/O operations to read and write files.

How It Works

The server starts and registers all available tools with the MCP framework.
It connects to the standard input/output for communication with AI assistants.
When a tool is invoked:
- For simple commands, it executes Godot with appropriate command-line arguments
- For complex operations, it creates a temporary GDScript file and executes it with Godot
- The results are returned to the AI assistant in a structured format

Development

Project Structure

src/index.ts: Main entry point
src/godot/commands.ts: Basic Godot commands
src/godot/operations.ts: Complex Godot operations using GDScript
src/tools/godot-tools.ts: MCP tool definitions for Godot
src/tools/file-tools.ts: MCP tool definitions for file operations
src/utils/godot-utils.ts: Utility functions for Godot integration

Building

npm run build

Example using Claude Desktop - Mac

In the tools, you should see the active MCP:

Here's an example prompt:

If you're interested, here's the full code that was created with that prompt. I tried to run it and there were errors, but it looks fixable.

License

ISC License

Categories

Current Category: godot

gdai-mcp-plugin-godot

godot-mcp-server