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., "@godot-mcp validate the main 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.
Godot MCP Server
godot-mcp lets MCP clients inspect, validate, test, export, and query Godot projects. It supports headless Godot commands and, optionally, live state from an open Godot editor.
Requirements
Node.js 18 or newer
Godot 4.1 or newer, installed locally
A Godot project containing
project.godot
The live-editor tools additionally require the MCP Bridge addon described below. The remaining tools run headlessly.
Related MCP server: godot-correctness-mcp
Install
From a local checkout
npm install
npm run buildFrom npm (after publication)
npx -y @zbrkic/godot-mcp --project /path/to/godot-project --godot /path/to/godotConfigure an MCP client
Always provide the project path. MCP desktop clients usually start servers in their own working directory, so automatic project discovery alone is not reliable.
{
"mcpServers": {
"godot": {
"command": "npx",
"args": ["-y", "@zbrkic/godot-mcp"],
"env": {
"GODOT_PROJECT_PATH": "C:/Source/my-game",
"GODOT_PATH": "C:/Program Files/Godot/Godot_v4.5.1-stable_win64_console.exe"
}
}
}
}The equivalent command-line options are:
godot-mcp --project /path/to/godot-project --godot /path/to/godotGODOT_PATH/--godot is optional only when the godot executable is already on PATH. On Windows, a _console.exe executable is preferred.
Enable live editor tools
Copy
godot-plugin/addons/mcp_bridgeto<your-project>/addons/mcp_bridge.In Godot, open Project > Project Settings > Plugins and enable MCP Bridge.
Keep the Godot editor open while using live tools.
The bridge listens on 127.0.0.1:7000 by default. Set mcp/plugin/port in project.godot to override it; the server reads that setting from the project configured above. Exclude addons/mcp_bridge/* from production export presets.
Tools
Project and export:
get_project_settings,list_export_presets,export_projectTests and validation:
run_tests,validate_scene,validate_script,run_scene,format_gdscriptScenes and resources:
inspect_scene_tree,find_nodes,get_node_properties,get_node_connections,list_resources,get_resource_dependencies,resolve_path,get_resource_infoDocumentation:
verify_api,get_helpLive editor:
get_editor_selection,get_open_scenes
Most tools return a structured JSON result with success, data, errors, warnings, and timing metadata.
Development and verification
npm test # TypeScript build plus MCP handshake and parser tests
npm run test:godot # GDScript syntax checks; requires GODOT_PATH or godot on PATH
npm pack --dry-run # Inspect the files that would be publishedGitHub Actions runs both the Node/MCP tests and Godot-addon checks on pushes and pull requests.
Release checklist
Update the version in
package.json.Run
npm test,npm run test:godot, andnpm pack --dry-run.Publish with
npm publishand create a matching GitHub release.
License
This project is licensed under the MIT License.
Available Tools
20 toolsexport_projectD
Exports project
Inputs: output (required), preset (required).
find_nodesD
Finds nodes in scene
Inputs: scene_path (required), type_filter, name_pattern.
format_gdscriptC
Formats GDScript
Inputs: script_path (required).
get_editor_selectionB
Gets current editor selection (requires open editor)
Inputs: no named parameters.
get_helpC
Gets Godot documentation
Inputs: search_term (required).
get_node_connectionsD
Gets node signals
Inputs: node_path (required), scene_path (required).
get_node_propertiesD
Gets node properties
Inputs: node_path (required), scene_path (required).
get_open_scenesB
Lists open scenes in editor (requires open editor)
Inputs: no named parameters.
get_project_settingsC
Parses project.godot
Inputs: prefix.
get_resource_dependenciesD
Gets resource deps
Inputs: resource_path (required).
get_resource_infoD
Gets detailed info about a resource
Inputs: resource_path (required).
inspect_scene_treeC
Returns node hierarchy
Inputs: scene_path (required).
list_export_presetsB
Returns export presets
Inputs: no named parameters.
list_resourcesC
Lists project resources
Inputs: type_filter.
resolve_pathC
Resolves a UID to a path or vice versa
Inputs: path_or_uid (required).
run_sceneC
Runs scene headlessly
Inputs: scene_path (required), timeout_ms.
run_testsB
Executes tests using GUT or a custom runner
Inputs: test_script.
validate_sceneC
Validates .tscn
Inputs: scene_path (required).
validate_scriptD
Validates .gd
Inputs: script_path (required).
verify_apiD
Checks Godot API
Inputs: class_name (required), method_name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
The tools are mostly distinct in purpose, covering different aspects like testing, scene inspection, resource management, and editor interactions. There is slight potential confusion between `inspect_scene_tree` and `find_nodes`, but they serve different goals (hierarchy vs. search). Overall, an agent can reliably select the right tool based on descriptions.
All tool names follow a consistent verb_noun pattern in snake_case, such as `run_tests`, `get_project_settings`, `validate_script`, and `list_resources`. The verbs are action-oriented and the nouns clearly indicate the target resource. This makes the toolset predictable and easy to navigate.
With 20 tools, this exceeds the typical 3-15 range, leaning toward the heavier side. However, each tool addresses a specific need in Godot development (testing, export, scene analysis, resource handling, editor access), so the count is justifiable albeit on the upper end. It feels slightly bloated but not excessive.
The toolset covers a broad range of Godot workflows, including project configuration, validation, running, formatting, scene/node introspection, resource management, and editor state. Missing features like creating or editing scenes/scripts are not core for an MCP that primarily aids analysis and execution. Minor gaps exist (e.g., no explicit node deletion), but agents can work around them.
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
MCP server for interacting with the Supabase platform
Remote MCP server to read and edit GanttFather projects: tasks, dates, dependencies, critical path.
Related MCP Servers
- Apache 2.0
- AlicenseNot gradedqualityBmaintenanceOffline static correctness MCP server for Godot 4.x GDScript projects that lints code, looks up API symbols, and validates scenes/resources, all without a running editor.240 npmCreative Commons Attribution Non Commercial No Derivatives 4.0 International
- AlicenseBqualityCmaintenanceConnects MCP-capable AI clients to a running Godot 4 editor for scene, node, project, and debug runtime operations via a local-first architecture.361MIT
- AlicenseBqualityFmaintenanceEnables Godot development via MCP with tools to inspect project configuration, scenes, runtime state, and execute allowed test commands.15MIT