Create, edit, and run Godot 4.5+ games through MCP tool calls.
Godot MCP
godot-mcp is a dependency-free MCP server for Godot 4.5+. It lets AI agents create, edit, and run full Godot games entirely through MCP tool calls.
Tested with Codex and Claude. Should also work with LMStudio, OpenCode, and any other MCP-compatible client.
Features
Detect Godot (
godot_detect_executable) : Locates and validates the Godot executable so every subsequent tool knows which engine binary to use.Create Project (
godot_create_project) : Scaffolds a brand-new Godot project with the chosen name and parent directory, delegating to Godot itself so the output stays compatible with newer 4.x releases.Create Folder (
godot_create_folder) : Creates project-relative folders with safesnake_casenaming for organizing assets, scenes, and scripts.Inspect Project Structure (
godot_get_project_structure) : Returns both nested structured entries and a human-readable tree string of all files and folders in the project.List Resources (
godot_list_resources) : Provides a fast grouped overview of scripts, shaders, scenes, and textures with counts, without manually globbing the project.Start Editor (
godot_start_project) : Opens the Godot editor for the project and returns a PID plus a log file path.Create Scene (
godot_create_scene) : Creates and saves a new scene with a Godot-stylesnake_case.tscnfilename andPascalCaseroot node name.Create Shader (
godot_create_shader) : Generates a.gdshaderfile from a starter template or explicit shader source code.Update Project Settings (
godot_update_project_settings) : Edits one or moreProjectSettingsparameters (app name, window size, etc.) through Godot itself. Accepts JSON-compatible values plus optional raw Godot expressions viavalue_godot.Attach Script (
godot_attach_script) : Attaches an existing.gdfile or creates a starter script that extends the target node's type before attaching it.Get Scene Tree (
godot_get_scene_tree) : Inspects a saved scene's node tree and parent/child structure using Godot's ownPackedScene.get_state().Validate Scene (
godot_validate_scene) : Dry-run parses a scene resource with a lightweight headless load so problems surface before a full run.Add Node (
godot_add_node) : Adds a new node of any instantiable Godot node type to an existing scene.Add Primitive Mesh (
godot_add_primitive_mesh) : Drops in aBoxMesh,CylinderMesh,SphereMesh, or other built-in primitive on aMeshInstance3Dnode for fast level blockout.Edit Primitive Mesh (
godot_edit_primitive_mesh) : Swaps the primitive type or changes parameters like size, height, radius, and segment counts.Edit Scene (
godot_edit_scene) : Renames a node, reparents it, deletes it, or combines those edits with transform changes in one save. Uses Godot to repack the scene.Get Node Properties (
godot_get_node_properties) : Returns the property list with serialized current values so object and vector values stay JSON-friendly.Get Node Transform (
godot_get_node_transform) : Inspects the root or a child node's transform section forNode2D,Node3D, andControlnodes.Update Node Transform (
godot_update_node_transform) : Adjusts position, rotation, scale, or other supported transform fields using JSON-friendly vector objects like{ "x": 10, "y": 20 }.Run Project (
godot_run_project) : Launches the project's main scene as a detached process, returning a PID plus a log file path.Run Scene (
godot_run_scene) : Launches a specific scene directly as a detached process.Run with Capture (
godot_run_with_capture) : Runs for a short capture window, then returns stdout, stderr, the Godot log file excerpt, and parsed debug lines for warnings and errors.Screenshot (
godot_screenshot) : Uses Godot's built-in movie writer to capture the last rendered PNG frame after running for a short duration.Search Docs (
godot_search_docs) : Searches a cached API dump generated from the selected Godot executable, so results stay aligned with the installed engine version.
The server also exposes MCP resource discovery over stdio, so clients can inspect a static tool catalog resource and a per-tool detail template without needing to call the tools first.
Requirements
- Python 3.10+
- Godot 4.5 or newer
Godot can be supplied either:
- per tool call with
godot_executable - globally with the
GODOT_EXECUTABLEenvironment variable
Examples:
/Applications/Godot.app/Contents/MacOS/Godot/Applications/Godot_mono.app/Contents/MacOS/Godot/usr/local/bin/godot4
Run It
From this repository:
PYTHONPATH=src python3 -m godot_mcp
Or install it:
python3 -m pip install -e .
godot-mcp
MCP Conf
Tools (24)
godot_detect_executableLocates and validates the Godot executable.godot_create_projectScaffolds a new Godot project.godot_create_folderCreates project-relative folders.godot_get_project_structureReturns project file structure.godot_list_resourcesProvides a grouped overview of project resources.godot_start_projectOpens the Godot editor for the project.godot_create_sceneCreates and saves a new scene.godot_create_shaderGenerates a .gdshader file.godot_update_project_settingsEdits project settings parameters.godot_attach_scriptAttaches or creates a script for a node.godot_get_scene_treeInspects a scene's node tree structure.godot_validate_sceneDry-run parses a scene resource.godot_add_nodeAdds a new node to an existing scene.godot_add_primitive_meshAdds a primitive mesh to a MeshInstance3D node.godot_edit_primitive_meshModifies primitive mesh parameters.godot_edit_sceneEdits scene nodes and transforms.godot_get_node_propertiesReturns node property list and values.godot_get_node_transformInspects node transform data.godot_update_node_transformUpdates node transform fields.godot_run_projectLaunches the project's main scene.godot_run_sceneLaunches a specific scene.godot_run_with_captureRuns a scene and captures output and errors.godot_screenshotCaptures a frame from the running project.godot_search_docsSearches cached Godot API documentation.Environment Variables
GODOT_EXECUTABLEPath to the Godot engine binaryConfiguration
{"mcpServers": {"godot-mcp": {"command": "python3", "args": ["-m", "godot_mcp"], "env": {"GODOT_EXECUTABLE": "/path/to/godot"}}}}