AI-godot-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AI-godot-mcp Add a new Sprite2D node to the current scene"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI-godot-mcp
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 statusget_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 filesadd_node- Add nodes to scene tree with automatic parent resolutionset_node_property- Modify node properties with type validationdelete_node- Delete nodes with full undo supportload_resource- Load and reference external resourcessave_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 generationget_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 validationuninstall- Clean removal of plugin from projectsversion- 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-mcpOther 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:
Open exactly one target Godot project.
Navigate to Project β Project Settings β Plugins.
Enable "AI Godot MCP".
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-mcpStarts 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 versionDisplay 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 toolsadd_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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Nifty's MCP server β exposes tasks, projects, messages, and files as tools for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Eβ¦
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables AI assistants to edit, run, inspect, and fix Godot 4 projects through an MCP server with dynamic tool groups and setup-gated capabilities.33397 npm273MIT
- AlicenseAqualityDmaintenanceProvides AI assistants with tools to launch the Godot editor, run projects, manipulate scenes, manage scripts, and control node properties through a standardized MCP interface.21MIT
- AlicenseBqualityDmaintenanceThis 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.100443 npm1MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.5MIT