Godot MCP Runtime

Overview Schema Source Related Servers Discussions Admin

batch_scene_operations

Destructive

Batch add_node, load_sprite, set_node_properties, and save calls into one Godot process, using a shared scene cache to avoid repeated startups when editing related scenes.

Instructions

Use this instead of chaining add_node / load_sprite / save_scene calls when you have multiple mutations on the same or related scenes - runs in one Godot process (~3s startup avoided per call) and shares an in-memory scene cache, saving once at the end. Each item picks its own sub-operation (add_node, load_sprite, set_node_properties, save) and supplies its own params; add_node items accept the same promoted spatial params (position, rotation, scale, visible, modulate) as the standalone tool; set_node_properties items accept the same per-update params (nodePath, property, value) and per-operation scenePath and abortOnError as the standalone tool; abortOnError stops on first failure (default false continues). Returns: results[] in input order, each tagged with operation and scenePath plus success or error. Errors while a Godot runtime session is active on this project; stop_project (or detach_project) clears it.

Input Schema

TableJSON Schema

Name	Required	Description
`operations`	Yes	Ordered list of scene operations. Each item has its own operation and scenePath.
`projectPath`	Yes	Path to the Godot project directory
`abortOnError`	No	Stop processing on first error (default: false)

Output Schema

TableJSON Schema

Name	Required	Description	Default
`results`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv3.6.0Sep 12, 2026

changedInput schema / properties / operations / items / properties / modulate / description

Previous value: -"[add_node] Color modulation — shorthand for properties.modulate"New value: +"[add_node] Color modulation - shorthand for properties.modulate"

changedInput schema / properties / operations / items / properties / position / description

Previous value: -"[add_node] Position — {\"x\",\"y\"} for 2D nodes, {\"x\",\"y\",\"z\"} for 3D. Shorthand for properties.position"New value: +"[add_node] Position - {\"x\",\"y\"} for 2D nodes, {\"x\",\"y\",\"z\"} for 3D. Shorthand for properties.position"

changedInput schema / properties / operations / items / properties / rotation / description

Previous value: -"[add_node] Rotation in radians — shorthand for properties.rotation"New value: +"[add_node] Rotation in radians - shorthand for properties.rotation"

changedInput schema / properties / operations / items / properties / scale / description

Previous value: -"[add_node] Vector2 scale — shorthand for properties.scale"New value: +"[add_node] Vector2 scale - shorthand for properties.scale"

changedInput schema / properties / operations / items / properties / visible / description

Previous value: -"[add_node] Visibility — shorthand for properties.visible"New value: +"[add_node] Visibility - shorthand for properties.visible"

Changed3 schema fields changedv3.5.0Sep 10, 2026

addedInput schema / properties / operations / items / properties / abortOnError

Added value: +{
+  "description": "[set_node_properties] Stop processing on first error",
+  "type": "boolean"
+}

changedInput schema / properties / operations / items / properties / operation / enum

Previous value: -[
-  "add_node",
-  "load_sprite",
-  "save"
-]New value: +[
+  "add_node",
+  "load_sprite",
+  "set_node_properties",
+  "save"
+]

addedInput schema / properties / operations / items / properties / updates

Added value: +{
+  "description": "[set_node_properties] Property updates to apply in this operation",
+  "items": {
+    "properties": {
+      "nodePath": {
+        "description": "Node path from scene root",
+        "type": "string"
+      },
+      "property": {
+        "description": "Property name in snake_case",
+        "type": "string"
+      },
+      "value": {
+        "description": "New value. Vector2/Vector3/Color auto-convert from {\"x\",\"y\"} / {\"x\",\"y\",\"z\"} / {\"r\",\"g\",\"b\",\"a\"} objects; primitives pass through"
+      }
+    },
+    "required": [
+      "nodePath",
+      "property",
+      "value"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed5 schema fields changedv3.3.0Sep 8, 2026

addedInput schema / properties / operations / items / properties / modulate

Added value: +{
+  "description": "[add_node] Color modulation — shorthand for properties.modulate",
+  "type": "object"
+}

addedInput schema / properties / operations / items / properties / position

Added value: +{
+  "description": "[add_node] Position — {\"x\",\"y\"} for 2D nodes, {\"x\",\"y\",\"z\"} for 3D. Shorthand for properties.position",
+  "type": "object"
+}

addedInput schema / properties / operations / items / properties / rotation

Added value: +{
+  "description": "[add_node] Rotation in radians — shorthand for properties.rotation",
+  "type": "number"
+}

addedInput schema / properties / operations / items / properties / scale

Added value: +{
+  "description": "[add_node] Vector2 scale — shorthand for properties.scale",
+  "type": "object"
+}

addedInput schema / properties / operations / items / properties / visible

Added value: +{
+  "description": "[add_node] Visibility — shorthand for properties.visible",
+  "type": "boolean"
+}

Addedv3.1.1May 17, 2026
Removedv3.0.0May 9, 2026
Addedv1.0.0Apr 30, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only give destructiveHint=true, so the description carries most of the weight. It discloses the single-process execution (~3s startup avoided per call), shared in-memory scene cache, save-once-at-end behavior, error semantics (abortOnError false continues by default), and the session precondition. It still leaves open whether partial mutations persist in the cache or whether the end-save can fail after errors, which is why it is not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One dense paragraph, front-loaded with the primary use case before diving into per-operation mechanics and return shape. Sentences are long but each carries distinct information (caching, error defaults, session lifecycle); minor redundancy with the schema descriptions of abortOnError.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so the return-value explanation is a bonus rather than a necessity, yet it still documents results[] ordering and tagging. Combined with the session-lifecycle caveat and caching behavior, the agent has enough to invoke correctly; only the fate of partial mutations on error remains unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by explaining that each array item selects its own sub-operation and params, that add_node accepts the same promoted spatial params as the standalone tool, and that set_node_properties mirrors the standalone per-update and per-operation fields. This clarifies the nested dispatch structure beyond the flat schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (batch) and resource (scene operations) with a clear scope: "multiple mutations on the same or related scenes" in one Godot process. It names the exact siblings it replaces (add_node / load_sprite / save_scene), so an agent can immediately distinguish it from the standalone tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use: "Use this instead of chaining add_node / load_sprite / save_scene calls when you have multiple mutations on the same or related scenes." It names the alternatives and the selecting condition, and adds a second condition (active Godot runtime session) with the clearing tools stop_project / detach_project.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.