Skip to main content
Glama
matula

Godot MCP Server

by matula

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

Related MCP server: Godot MCP

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

Installation

  1. Clone this repository:

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

    npm install
  3. 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:

  1. Locate the Claude Desktop configuration file:

    • Generally on macOS: /Users/{username}/Library/Application Support/Claude/claude_desktop_config.json

  2. 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:

  1. MCP Server Core: Uses the @modelcontextprotocol/sdk to create a server that communicates with AI assistants.

  2. Tools Registration: Tools are registered with the MCP server to expose functionality to AI assistants.

  3. 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.

  4. File Operations: Basic file I/O operations to read and write files.

How It Works

  1. The server starts and registers all available tools with the MCP framework.

  2. It connects to the standard input/output for communication with AI assistants.

  3. 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:

claude-desktop-tools.png

Here's an example prompt:

claude-desktop-example-prompt.png

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

Available Tools

12 tools
add_nodeD
ParametersJSON Schema
NameRequiredDescriptionDefault
nodeNameYesName of the node to add
nodeTypeYesType of the node
parentPathYesPath to the parent node
projectPathYesAbsolute path to the Godot project directory

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_projectD
ParametersJSON Schema
NameRequiredDescriptionDefault
templateNoProject template (3d, 2d, or empty)
projectNameYesName of the project to create
parentDirectoryYesDirectory to create the project in

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_sceneD
ParametersJSON Schema
NameRequiredDescriptionDefault
nodeTypeNoType of the root node (default: Node3D)
sceneNameYesName of the scene to create
projectPathYesAbsolute path to the Godot project directory

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_debug_outputD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_scene_treeD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesAbsolute path to the Godot project directory

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

godot_versionD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

launch_editorD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesAbsolute path to the Godot project directory

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsD
ParametersJSON Schema
NameRequiredDescriptionDefault
directoryPathYesDirectory to search for Godot projects

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileD
ParametersJSON Schema
NameRequiredDescriptionDefault
filePathYesAbsolute path to the file to read

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_projectD
ParametersJSON Schema
NameRequiredDescriptionDefault
projectPathYesAbsolute path to the Godot project directory

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stop_projectD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_fileD
ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesContent to write to the file
filePathYesAbsolute path to the file to write

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 12 tool updatesv1.0.0
    • First observedadd_node
    • First observedcreate_project
    • First observedcreate_scene
    • First observedget_debug_output
    • First observedget_scene_tree
    • First observedgodot_version
    • First observedlaunch_editor
    • First observedlist_projects
    • First observedread_file
    • First observedrun_project
    • First observedstop_project
    • First observedwrite_file

TDQS

C2.1/5.0
Disambiguation5/5

Each tool targets a distinct action (e.g., project management, scene editing, file I/O) with unique names, making confusion unlikely despite missing descriptions.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., list_projects, create_scene, write_file), ensuring predictability.

Tool Count5/5

12 tools cover a broad range of Godot interactions (project, editor, scene, debug, file) without being excessive or trivial.

Completeness4/5

Core workflows are covered, but missing operations like remove_node or update project limit some lifecycle completeness.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    F
    maintenance
    Enables AI assistants to interact with the Godot game engine by launching the editor, running projects, capturing debug output, managing scenes and nodes, and controlling project execution through a standardized interface.
    18
    248
    11
    MIT
  • A
    license
    B
    quality
    Not graded
    maintenance
    Enables AI assistants to interact with the Godot game engine by launching the editor, running projects, capturing debug output, managing scenes and nodes, and controlling project execution through a standardized interface.
    14
    248
    1
    -
  • A
    license
    B
    quality
    C
    maintenance
    Enables AI assistants to interact with the Godot game engine, including launching the editor, running projects, capturing debug output, and managing scenes.
    84
    1
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/matula/godot-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server