• Check limits before you act. Before any tool that uses file paths, check that the path is correct and fits that tool's rules (see "Path Rules").
• Read errors as clues. When a tool fails, it returns text like Error: <reason>. If there are solutions, it also adds Possible solutions:\n- .... Read this text and fix your call. Do not repeat the same wrong call.
• Do not assume. Verify. Do not assume a scene was created. Check the result before you add nodes to it.
• Respect path safety. projectPath and directory must be absolute paths. Other path args must be relative to the project. Never use ...
• Check docs before you code. When you are not sure about a Godot Class, Signal, or Method, first search the official docs with search_godot_docs and fetch_godot_docs. Then act.
• Keep the Godot process clean. Keep only one running project at a time. If one is already running, call stop_project or start a fresh run_project before doing more.

Tool Reference (all 16 tools)

Every tool takes parameters in JSON Schema form (type, required, description). Below are all tools. Required args are marked required; optional args are marked optional.

A. Editor / Project Lifecycle

B. Project Discovery / Inspection

C. Scene / Node Editing (runs GDScript under the hood)

D. Godot Official Docs (network only, no Godot binary needed)

Important about search: search_godot_docs matches keywords. It can return several pages that mention the word, not just one exact page. So pick the most relevant result, then call fetch_godot_docs on its url. If the result looks wrong, search again with different words. Do not assume the search result points to the exact page you wanted.

Per-Chat Settings

LM Studio shows these settings as a UI. You do not manage them directly, but they change tool behavior:

Path Rules (break these and the tool returns an Error)

• projectPath and directory must be absolute paths (e.g. /home/user/projects/my_game).
• scenePath, texturePath, outputPath, filePath are relative to the project (e.g. scenes/level1.tscn, characters/hero.png). No ...
• nodeType and rootNodeType must be built-in Godot class names (e.g. Node2D, CharacterBody2D, Sprite2D, CollisionShape2D, GridMap). Not a path, not res://....
• Several tools check that the scene file exists first: add_node, load_sprite, save_scene, export_mesh_library. They need the .tscn to already exist. Use create_scene first if it does not exist.
• get_uid and update_project_uids need Godot 4.4+. If the version is lower, they return a clear error and tell you to upgrade.
• If Godot is not found, most engine tools tell you to set godotPath or GODOT_PATH.

Response Format and Error Handling

• Success: Most tools return plain text (e.g. Scene created successfully at: ...). The tools get_debug_output, stop_project, list_projects, get_project_info, and search_godot_docs return a JSON string. You can parse it.
• Failure: The tool returns text starting with Error: . If there are solutions, it adds a Possible solutions: list. For example, when Godot cannot be launched you will see Error: Failed to create scene: Failed to spawn Godot executable "<path>": ENOENT — this means Godot is missing or the path is wrong, so set godotPath / GODOT_PATH or install Godot before retrying.
• Your job: Treat any Error: text as debug info. Fix the argument or the prior step, then call again. Do not repeat the same clear error more than twice. If it still fails, search the docs or change your approach, and tell the user what happened.

Usage Examples

Example 1: List projects and get info

// 1) Find Godot projects under a root folder
{ "tool": "list_projects", "arguments": { "directory": "/home/user/projects", "recursive": true } }

// Returns something like:
// [ { "path": "/home/user/projects/arcade", "name": "arcade" }, ... ]

// 2) Get details about that project
{ "tool": "get_project_info", "arguments": { "projectPath": "/home/user/projects/arcade" } }
// Returns:
// { "name": "arcade", "path": "...", "godotVersion": "Godot 4.4-stable ...", "structure": { "scenes": 3, "scripts": 8, "assets": 12, "other": 2 } }

Example 2: Create a scene, add a node, load a sprite (these steps depend on each other)

// 1) Create a Node2D scene
{ "tool": "create_scene", "arguments": { "projectPath": "/home/user/projects/arcade", "scenePath": "ui/hud.tscn", "rootNodeType": "Node2D" } }

// 2) Add a Sprite2D node to it (the scene must exist first)
{ "tool": "add_node", "arguments": {
    "projectPath": "/home/user/projects/arcade",
    "scenePath": "ui/hud.tscn",
    "nodeType": "Sprite2D",
    "nodeName": "Background",
    "parentNodePath": "root",
    "properties": { "offset": { "x": 0, "y": 0 } }
} }

// 3) Load a texture into that node
{ "tool": "load_sprite", "arguments": {
    "projectPath": "/home/user/projects/arcade",
    "scenePath": "ui/hud.tscn",
    "nodePath": "root/Background",
    "texturePath": "assets/bg.png"
} }

Example 3: Run the project and read debug output

// 1) Run in headless debug mode, opening a scene
{ "tool": "run_project", "arguments": { "projectPath": "/home/user/projects/arcade", "scene": "scenes/main.tscn" } }

// 2) Read the output (may be empty, or show errors)
{ "tool": "get_debug_output", "arguments": {} }

// ... fix any problems ...

// 3) Stop when done
{ "tool": "stop_project", "arguments": {} }

Example 4: Check official docs before writing GDScript

// 1) Search the docs for CharacterBody3D
{ "tool": "search_godot_docs", "arguments": { "query": "CharacterBody3D movement physics" } }
// Returns: [ { "title": "...", "url": "https://docs.godotengine.org/en/stable/classes/class_characterbody3d.html", "snippet": "..." }, ... ]

// 2) Read the most relevant page (use the url from step 1)
{ "tool": "fetch_godot_docs", "arguments": { "url": "https://docs.godotengine.org/en/stable/classes/class_characterbody3d.html", "maxChars": 4000 } }

// 3) Follow the docs, then use add_node to create a CharacterBody3D node with the right collision setup

Development Scenarios

Here are common Godot tasks and the tool call order to use. Adjust as needed. Read each result before choosing the next step.

Scenario A: Build a minimal 2D platformer prototype

Goal: make a runnable minimum prototype with a hero, a scene, and collisions.

• list_projects — confirm the project exists (if not, ask the user, or create the project.godot first).
• get_project_info — see the current structure (scene/script counts) so you do not rebuild what already exists.
• Search API: search_godot_docs("CharacterBody2D"). If needed, fetch_godot_docs to read how move_and_slide works.
• create_scene — make the main scene (e.g. scenes/level.tscn, root Node2D).
• add_node — add the hero as CharacterBody2D (nodeName: Player), with properties like collision_layer.
• add_node — add a CollisionShape2D child, or create a StaticBody2D for the ground.
• load_sprite — give the hero and ground textures.
• run_project (with scene: scenes/level.tscn) → get_debug_output to look for script errors.
• If there are errors, fix the GDScript (you edit the .gd file directly), then use save_scene and run again to verify.
• stop_project when done.

Scenario B: Debug a scene that does not work

Principle: reproduce, narrow down, fix, verify.

• run_project (with scene) to reproduce.
• get_debug_output to read stdout/stderr. Look for ERROR:, Invalid call, and script line numbers.
• If an error points to a method that does not exist, use search_godot_docs + fetch_godot_docs to find the correct signature.
• After you fix the script (you edit the .gd file directly), call save_scene if the scene structure changed, then run_project to verify.
• Once fixed, stop_project. Never leave a process running.

Scenario C: Build a 3D level with GridMap

• search_godot_docs("GridMap") and search_godot_docs("MeshLibrary"). Read the pages if needed.
• create_scene — make a 3D scene (root Node3D, or WorldEnvironment, etc.).
• add_node — add a GridMap node. Set properties like cell_size and cell_half_size per the docs.
• If you have a .res MeshLibrary: use add_node to create the related node, then fill the GridMap in GDScript (the tool builds the structure).
• To export a MeshLibrary from an existing 3D scene: export_mesh_library (outputPath like assets/mesh_lib.res; optional meshItemNames subset).
• run_project + get_debug_output to verify the level works.

Scenario D: Use global classes and scripts

godot-mcp's add_node, when it needs to load a script by class name, only accepts names from the Project Global Class Registry. This is a safety choice (it blocks arbitrary paths like res://evil.gd). So:

• First check that your target script is registered in the Project Global Class Registry (in project.godot / project settings).
• If it is not registered, you cannot load it through the tool. Ask the user to register it first, or use a built-in class name.
• After registration, call add_node with nodeType set to the registered class name. Or use a built-in class name and attach the script another way.

Scenario E: Manage UIDs in a Godot 4.4+ project

• get_godot_version — confirm it is >= 4.4.
• get_uid (filePath like scenes/level.tscn) to get the UID of one file.
• To rebuild all UIDs at once: update_project_uids.
• If the version is < 4.4, the tool returns "UIDs require Godot 4.4+". Then use resource paths (res://...) instead of UIDs.

Workflow Checklist (check before any task that edits a project/scene)

• I used list_projects / get_project_info to confirm the project and path.
• Required args are filled, and paths follow the "absolute vs relative" rule and have no ...
• For built-in classes, nodeType / rootNodeType use valid class names.
• Before a scene tool, I confirmed the scene file exists (or called create_scene first).
• For any Godot API I was unsure about, I searched the docs with search_godot_docs and fetch_godot_docs.
• After running the project, I end with stop_project and leave no process running.
• I read each tool result, and when I got an Error: I fixed it instead of repeating the same call.

Quick Map: What do you want? → Which tool?

Notes

• This tool set comes from Coding-Solo/godot-mcp (https://github.com/Coding-Solo/godot-mcp). It is written in TypeScript and runs inside the Node.js environment built into LM Studio.
• Engine tools (A, B, C) need a working Godot executable on this machine. If they return Error: Failed to spawn Godot executable "<path>": <ENOENT|EACCES|EPERM> (or any "Could not find Godot executable" message), set the godotPath setting or the GODOT_PATH environment variable, or install Godot Engine. These tools now report this error explicitly instead of silently pretending the operation succeeded.
• Docs tools (D) are network only. They do not need the Godot binary, so you can use them anytime.

• Check limits before you act. Before any tool that uses file paths, check that the path is correct and fits that tool's rules (see "Path Rules").
• Read errors as clues. When a tool fails, it returns text like Error: <reason>. If there are solutions, it also adds Possible solutions:\n- .... Read this text and fix your call. Do not repeat the same wrong call.
• Do not assume. Verify. Do not assume a scene was created. Check the result before you add nodes to it.
• Respect path safety. projectPath and directory must be absolute paths. Other path args must be relative to the project. Never use ...
• Check docs before you code. When you are not sure about a Godot Class, Signal, or Method, first search the official docs with search_godot_docs and fetch_godot_docs. Then act.
• Keep the Godot process clean. Keep only one running project at a time. If one is already running, call stop_project or start a fresh run_project before doing more.

Tool Reference (all 16 tools)

Every tool takes parameters in JSON Schema form (type, required, description). Below are all tools. Required args are marked required; optional args are marked optional.

A. Editor / Project Lifecycle

B. Project Discovery / Inspection

C. Scene / Node Editing (runs GDScript under the hood)

D. Godot Official Docs (network only, no Godot binary needed)

Important about search: search_godot_docs matches keywords. It can return several pages that mention the word, not just one exact page. So pick the most relevant result, then call fetch_godot_docs on its url. If the result looks wrong, search again with different words. Do not assume the search result points to the exact page you wanted.

Per-Chat Settings

LM Studio shows these settings as a UI. You do not manage them directly, but they change tool behavior:

Path Rules (break these and the tool returns an Error)

• projectPath and directory must be absolute paths (e.g. /home/user/projects/my_game).
• scenePath, texturePath, outputPath, filePath are relative to the project (e.g. scenes/level1.tscn, characters/hero.png). No ...
• nodeType and rootNodeType must be built-in Godot class names (e.g. Node2D, CharacterBody2D, Sprite2D, CollisionShape2D, GridMap). Not a path, not res://....
• Several tools check that the scene file exists first: add_node, load_sprite, save_scene, export_mesh_library. They need the .tscn to already exist. Use create_scene first if it does not exist.
• get_uid and update_project_uids need Godot 4.4+. If the version is lower, they return a clear error and tell you to upgrade.
• If Godot is not found, most engine tools tell you to set godotPath or GODOT_PATH.

Response Format and Error Handling

• Success: Most tools return plain text (e.g. Scene created successfully at: ...). The tools get_debug_output, stop_project, list_projects, get_project_info, and search_godot_docs return a JSON string. You can parse it.
• Failure: The tool returns text starting with Error: . If there are solutions, it adds a Possible solutions: list. For example, when Godot cannot be launched you will see Error: Failed to create scene: Failed to spawn Godot executable "<path>": ENOENT — this means Godot is missing or the path is wrong, so set godotPath / GODOT_PATH or install Godot before retrying.
• Your job: Treat any Error: text as debug info. Fix the argument or the prior step, then call again. Do not repeat the same clear error more than twice. If it still fails, search the docs or change your approach, and tell the user what happened.

Usage Examples

Example 1: List projects and get info

// 1) Find Godot projects under a root folder
{ "tool": "list_projects", "arguments": { "directory": "/home/user/projects", "recursive": true } }

// Returns something like:
// [ { "path": "/home/user/projects/arcade", "name": "arcade" }, ... ]

// 2) Get details about that project
{ "tool": "get_project_info", "arguments": { "projectPath": "/home/user/projects/arcade" } }
// Returns:
// { "name": "arcade", "path": "...", "godotVersion": "Godot 4.4-stable ...", "structure": { "scenes": 3, "scripts": 8, "assets": 12, "other": 2 } }

Example 2: Create a scene, add a node, load a sprite (these steps depend on each other)

// 1) Create a Node2D scene
{ "tool": "create_scene", "arguments": { "projectPath": "/home/user/projects/arcade", "scenePath": "ui/hud.tscn", "rootNodeType": "Node2D" } }

// 2) Add a Sprite2D node to it (the scene must exist first)
{ "tool": "add_node", "arguments": {
    "projectPath": "/home/user/projects/arcade",
    "scenePath": "ui/hud.tscn",
    "nodeType": "Sprite2D",
    "nodeName": "Background",
    "parentNodePath": "root",
    "properties": { "offset": { "x": 0, "y": 0 } }
} }

// 3) Load a texture into that node
{ "tool": "load_sprite", "arguments": {
    "projectPath": "/home/user/projects/arcade",
    "scenePath": "ui/hud.tscn",
    "nodePath": "root/Background",
    "texturePath": "assets/bg.png"
} }

Example 3: Run the project and read debug output

// 1) Run in headless debug mode, opening a scene
{ "tool": "run_project", "arguments": { "projectPath": "/home/user/projects/arcade", "scene": "scenes/main.tscn" } }

// 2) Read the output (may be empty, or show errors)
{ "tool": "get_debug_output", "arguments": {} }

// ... fix any problems ...

// 3) Stop when done
{ "tool": "stop_project", "arguments": {} }

Example 4: Check official docs before writing GDScript

// 1) Search the docs for CharacterBody3D
{ "tool": "search_godot_docs", "arguments": { "query": "CharacterBody3D movement physics" } }
// Returns: [ { "title": "...", "url": "https://docs.godotengine.org/en/stable/classes/class_characterbody3d.html", "snippet": "..." }, ... ]

// 2) Read the most relevant page (use the url from step 1)
{ "tool": "fetch_godot_docs", "arguments": { "url": "https://docs.godotengine.org/en/stable/classes/class_characterbody3d.html", "maxChars": 4000 } }

// 3) Follow the docs, then use add_node to create a CharacterBody3D node with the right collision setup

Development Scenarios

Here are common Godot tasks and the tool call order to use. Adjust as needed. Read each result before choosing the next step.

Scenario A: Build a minimal 2D platformer prototype

Goal: make a runnable minimum prototype with a hero, a scene, and collisions.

• list_projects — confirm the project exists (if not, ask the user, or create the project.godot first).
• get_project_info — see the current structure (scene/script counts) so you do not rebuild what already exists.
• Search API: search_godot_docs("CharacterBody2D"). If needed, fetch_godot_docs to read how move_and_slide works.
• create_scene — make the main scene (e.g. scenes/level.tscn, root Node2D).
• add_node — add the hero as CharacterBody2D (nodeName: Player), with properties like collision_layer.
• add_node — add a CollisionShape2D child, or create a StaticBody2D for the ground.
• load_sprite — give the hero and ground textures.
• run_project (with scene: scenes/level.tscn) → get_debug_output to look for script errors.
• If there are errors, fix the GDScript (you edit the .gd file directly), then use save_scene and run again to verify.
• stop_project when done.

Scenario B: Debug a scene that does not work

Principle: reproduce, narrow down, fix, verify.

• run_project (with scene) to reproduce.
• get_debug_output to read stdout/stderr. Look for ERROR:, Invalid call, and script line numbers.
• If an error points to a method that does not exist, use search_godot_docs + fetch_godot_docs to find the correct signature.
• After you fix the script (you edit the .gd file directly), call save_scene if the scene structure changed, then run_project to verify.
• Once fixed, stop_project. Never leave a process running.

Scenario C: Build a 3D level with GridMap

• search_godot_docs("GridMap") and search_godot_docs("MeshLibrary"). Read the pages if needed.
• create_scene — make a 3D scene (root Node3D, or WorldEnvironment, etc.).
• add_node — add a GridMap node. Set properties like cell_size and cell_half_size per the docs.
• If you have a .res MeshLibrary: use add_node to create the related node, then fill the GridMap in GDScript (the tool builds the structure).
• To export a MeshLibrary from an existing 3D scene: export_mesh_library (outputPath like assets/mesh_lib.res; optional meshItemNames subset).
• run_project + get_debug_output to verify the level works.

Scenario D: Use global classes and scripts

godot-mcp's add_node, when it needs to load a script by class name, only accepts names from the Project Global Class Registry. This is a safety choice (it blocks arbitrary paths like res://evil.gd). So:

• First check that your target script is registered in the Project Global Class Registry (in project.godot / project settings).
• If it is not registered, you cannot load it through the tool. Ask the user to register it first, or use a built-in class name.
• After registration, call add_node with nodeType set to the registered class name. Or use a built-in class name and attach the script another way.

Scenario E: Manage UIDs in a Godot 4.4+ project

• get_godot_version — confirm it is >= 4.4.
• get_uid (filePath like scenes/level.tscn) to get the UID of one file.
• To rebuild all UIDs at once: update_project_uids.
• If the version is < 4.4, the tool returns "UIDs require Godot 4.4+". Then use resource paths (res://...) instead of UIDs.

Workflow Checklist (check before any task that edits a project/scene)

• I used list_projects / get_project_info to confirm the project and path.
• Required args are filled, and paths follow the "absolute vs relative" rule and have no ...
• For built-in classes, nodeType / rootNodeType use valid class names.
• Before a scene tool, I confirmed the scene file exists (or called create_scene first).
• For any Godot API I was unsure about, I searched the docs with search_godot_docs and fetch_godot_docs.
• After running the project, I end with stop_project and leave no process running.
• I read each tool result, and when I got an Error: I fixed it instead of repeating the same call.

Quick Map: What do you want? → Which tool?

Notes

• This tool set comes from Coding-Solo/godot-mcp (https://github.com/Coding-Solo/godot-mcp). It is written in TypeScript and runs inside the Node.js environment built into LM Studio.
• Engine tools (A, B, C) need a working Godot executable on this machine. If they return Error: Failed to spawn Godot executable "<path>": <ENOENT|EACCES|EPERM> (or any "Could not find Godot executable" message), set the godotPath setting or the GODOT_PATH environment variable, or install Godot Engine. These tools now report this error explicitly instead of silently pretending the operation succeeded.
• Docs tools (D) are network only. They do not need the Godot binary, so you can use them anytime.