Skip to main content
Glama
AI-godot-mcp

AI-godot-mcp

by DC925928496

AI-godot-mcp

MCP Server Made with Godot GDScript Node.js WebSocket License: MIT

δΈ­ζ–‡ζ–‡ζ‘£

Production-grade Godot MCP service for AI-driven game development.

Inspired by dpeachpeach/godot-mcp

Vision

AI-godot-mcp aims to let ordinary people build Godot games with coding agents such as Codex, using this project as the editor bridge and the Godot editor as the live development surface.

The long-term goal is not to hard-code game-building workflows into MCP. The goal is to give agents a reliable Godot execution layer: the agent does the planning and reasoning, while AI-godot-mcp safely inspects, mutates, runs, and observes the editor on the agent's behalf.

Related MCP server: godot-ai-mcp

What Comes Next

The repository already has the low-level MCP bridge. The next direction is to make that bridge a better execution substrate for Codex-style agents:

  • keep workflow intelligence in the agent layer, while expanding MCP into a more complete and composable Godot capability surface

  • strengthen the observe-repair loop with clearer in-editor status, operation history, and run feedback

  • lower the onboarding cost with starter templates, example projects, and docs that show how agents can drive the editor effectively

  • expand the Godot authoring surface toward signals, input maps, scene instancing, autoloads, and common UI flows

Features

πŸ” Project Inspection

  • get_project_context - Retrieve Godot version, project name, and plugin status

  • get_scene_tree - Get current scene node tree (supports depth limit and type filtering)

  • get_editor_logs - Fetch editor output panel logs (supports timestamp and level filtering)

🎨 Scene Editing

  • create_scene - Create new scene files

  • add_node - Add nodes to scene tree with automatic parent resolution

  • set_node_property - Modify node properties with type validation

  • delete_node - Delete nodes with full undo support

  • load_resource - Load and reference external resources

  • save_current_scene - Save current scene to disk

⚑ Transaction Management

  • begin_ai_action / end_ai_action - Atomic batch operations with native UndoRedo integration

πŸ“ Script Management

  • attach_script - Attach GDScript to nodes with automatic template generation

  • get_resource_uid - Get resource UID for cross-reference validation

▢️ Scene Execution

  • play_current_scene - Run current scene in editor (F6)

  • stop_running_scene - Stop running scene (F8)

πŸ› οΈ CLI Tools

  • install - Deploy plugin to Godot projects with version validation

  • uninstall - Clean removal of plugin from projects

  • version - Display version and compatibility information

Requirements

  • Godot: 4.6.x only

  • Node.js: β‰₯20.0.0

Quick Start

Choose one MCP server startup method, then load the Godot editor plugin for the project you want the agent to operate on.

Option 1: npx

npx ai-godot-mcp install "<godot-project-path>"

Use this when you want npm to download and run the published package on demand. The MCP client starts the stdio server with npx ai-godot-mcp.

Claude Code

claude mcp add ai-godot-mcp -- npx ai-godot-mcp

Other MCP Clients

Use this server configuration:

{
  "mcpServers": {
    "ai-godot-mcp": {
      "command": "npx",
      "args": ["ai-godot-mcp"]
    }
  }
}

Option 2: GitHub Releases

Use this when you downloaded the packaged release artifact instead of pulling from npm at runtime.

npm install -g "./ai-godot-mcp-<version>.tgz"
ai-godot-mcp install "<godot-project-path>"

Then point your MCP client at the installed command:

claude mcp add ai-godot-mcp -- ai-godot-mcp
{
  "mcpServers": {
    "ai-godot-mcp": {
      "command": "ai-godot-mcp",
      "args": []
    }
  }
}

If a release also provides plugin-only.zip, that file only installs the Godot addon manually. It does not start the Node MCP server; use one of the server startup methods above or below.

Option 3: Build from Source

Use this when developing the project locally or testing unpublished changes.

git clone https://github.com/DC925928496/AI-godot-mcp.git
cd AI-godot-mcp
npm install
npm run build
node build/cli/index.js install "<godot-project-path>"

Then point your MCP client to the built server entrypoint:

claude mcp add ai-godot-mcp -- node "E:/code/AI-godot-mcp/build/index.js"
{
  "mcpServers": {
    "ai-godot-mcp": {
      "command": "node",
      "args": ["E:/code/AI-godot-mcp/build/index.js"]
    }
  }
}

Re-run npm run build after changing TypeScript source.

Load the Godot Plugin

After installing or copying the addon:

  1. Open exactly one target Godot project.

  2. Navigate to Project β†’ Project Settings β†’ Plugins.

  3. Enable "AI Godot MCP".

  4. Restart or reload your MCP client so it discovers the server tools.

Only one Godot project should load the plugin at a time. The plugin listens on local port 6550; if two editors load it, one editor may fail to bind the port or the MCP server may connect to the wrong project. Before switching projects, disable the plugin or close the current Godot editor, then enable it in the next project.

Architecture

AI-godot-mcp uses a WebSocket communication architecture:

  • Node MCP Server (WebSocket client) ↔ Godot Editor Plugin (WebSocket server on port 6550)

  • All write operations integrate with Godot's native UndoRedo system, supporting atomic transactions

  • Unified response format: {ok: true, data} or {ok: false, error: {code, message, suggestions}}

CLI Commands

MCP server

npx ai-godot-mcp

Starts the MCP server over stdio. MCP clients usually run this command for you. For a release package installed globally, use ai-godot-mcp. For a source checkout, use node build/index.js after npm run build.

install

npx ai-godot-mcp install "<project-path>"

Deploy plugin to Godot project with version compatibility validation (Godot 4.6.x only).

uninstall

npx ai-godot-mcp uninstall "<project-path>"

Remove addons/ai_godot_mcp/ directory from project.

version

npx ai-godot-mcp version

Display version information and supported Godot versions.

Troubleshooting

  • Godot version mismatch β†’ Ensure you're using Godot 4.6.x (verify with godot --version)

  • Plugin not enabled β†’ Check Project β†’ Project Settings β†’ Plugins in editor, ensure "AI Godot MCP" is checked

  • WebSocket connection failed β†’ Confirm plugin is started and port 6550 is not occupied

  • Tool call timeout β†’ Ensure Godot editor is running and plugin is loaded

License

MIT

Available Tools

28 tools
add_nodeC

Add a node to the scene tree

Inputs: node_name (required), node_type (required), parent_path (required).

add_node_to_groupC

Add a node to a group

Inputs: node_path (required), group_name (required), persistent.

attach_scriptC

Attach a GDScript to a node

Inputs: node_path (required), script_path (required).

begin_ai_actionC

Begin a transaction for multiple operations

Inputs: name (required).

bind_input_keyC

Create or extend a keyboard input binding

Inputs: key (required), action_name (required), alt, ctrl, +2 more.

connect_signalC

Connect a signal between two nodes

Inputs: method_name (required), signal_name (required), source_node_path (required), target_node_path (required), +2 more.

create_sceneC

Create a new scene file

Inputs: scene_name (required), root_node_type.

delete_nodeC

Delete a node from the scene

Inputs: node_path (required).

disconnect_signalC

Disconnect a signal between two nodes

Inputs: method_name (required), signal_name (required), source_node_path (required), target_node_path (required).

duplicate_nodeC

Duplicate a node

Inputs: node_path (required), new_name.

end_ai_actionB

Commit the current transaction

Inputs: no named parameters.

get_editor_logsC

Get editor logs with filters

Inputs: filter_level, since_timestamp.

get_input_mapA

List project input actions

Inputs: no named parameters.

get_project_contextB

Get Godot project context

Inputs: no named parameters.

get_resource_uidC

Get resource UID and type

Inputs: resource_path (required).

get_scene_treeA

Get current scene node tree

Inputs: no named parameters.

instantiate_sceneC

Instantiate a PackedScene into the current scene

Inputs: scene_path (required), parent_path (required), node_name.

list_autoloadsA

List project autoloads

Inputs: no named parameters.

load_resourceD

Load a resource reference

Inputs: resource_path (required), resource_type.

open_sceneB

Open a Godot scene by res:// path

Inputs: scene_path (required).

play_current_sceneB

Run current scene (F6)

Inputs: no named parameters.

remove_autoloadC

Remove an autoload

Inputs: name (required).

remove_node_from_groupC

Remove a node from a group

Inputs: node_path (required), group_name (required).

reparent_nodeC

Reparent a node to a new parent

Inputs: node_path (required), new_parent_path (required), keep_global_transform.

save_current_sceneB

Save the current scene

Inputs: no named parameters.

set_autoloadC

Set or update an autoload

Inputs: name (required), path (required), is_singleton.

set_node_propertyC

Set a property on a node

Inputs: property (required), node_path (required), value.

stop_running_sceneB

Stop running scene (F8)

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 28 tools

    Disambiguation5/5

    Each tool has a clear, distinct purpose. Opposing operations (add/remove, connect/disconnect) are paired, and context-specific tools like editor logs and scene tree are separate from node manipulation tools. No two tools overlap in function.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., add_node, play_current_scene). The verb choice is precise and shows a uniform style throughout the set.

    Tool Count4/5

    With 28 tools covering scene editing, node operations, signals, input, autoloads, and editor utilities, the count is on the higher side but justified by the breadth of Godot functionality. It remains manageable and well-scoped.

    Completeness3/5

    The toolset covers many core operations (CRUD for nodes, scenes, signals, autoloads) but lacks tools for creating scripts or resources directly. Missing rename_node and explicit resource creation are gaps that agents may need to work around.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables AI assistants to edit, run, inspect, and fix Godot 4 projects through an MCP server with dynamic tool groups and setup-gated capabilities.
      33
      397 npm
      273
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides AI assistants with tools to launch the Godot editor, run projects, manipulate scenes, manage scripts, and control node properties through a standardized MCP interface.
      21
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      This MCP server allows AI assistants to control the Godot editor and running games, enabling scene creation, script editing, input simulation, and gameplay testing through 174 tools.
      100
      443 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to inspect, author, debug, simulate, and visually verify Godot 4.x projects through standard MCP tools, including scene editing, runtime control, and viewport capture.
      5
      MIT