The MCP that understands your Godot project

Spatial understanding of .tscn: positions, distances, directions, bounds. ALWAYS call before placing/moving 3D objects.

> scene_map main.tscn --focus Player --radius 10
  Player (0,1,0) → Shelf (2,0,3) 3.2m east → Door (5,0,0) 5.1m east

Find safe placement positions for new objects. Checks Marker3D slots first, then grid-searches nearby space.

> placement --near Printer --object_type shelf
  Suggestion 1: (4.2, 0, -1.8) confidence: 0.95 ✓ marker slot

Automated 3D scene linter: floating objects, scale mismatches, z-fighting, overlapping instances.

> spatial_audit main.tscn
  ⚠ 2 floating objects, 1 scale mismatch, 0 z-fighting

Complete dependency graph: what file emits, who listens, what it imports, who imports it, impact rating.

> dependency_graph Player.gd
  Player.gd → Health.gd → UI/HUD.tscn (impact: high)

Project-wide signal wiring: who emits, who listens, orphan/missing signals.

> signal_map
  health_changed: Player.gd emits → HUD.gd, GameManager.gd

Predict what breaks BEFORE making change. Returns affected files, callers, risk level.

> impact_check Player.gd
  7 files affected, 3 signals, risk: high

Convention check: missing type hints, missing class_name, orphan signals, naming violations.

> validate
  ✓ 42 rules passed, ⚠ 2 warnings (missing type hints)

Trace execution flow from function or signal through entire codebase.

> trace_flow start_print_job --depth 10
  PrintManager._ready → queue_job → Worker.execute → done signal

Architecture, autoloads, conventions, file counts. Call FIRST in every session.

> project_summary
  48 scripts, 23 scenes, 5 autoloads, 156 signals mapped

File's public API, dependencies, signals, who imports this file, scene usage.

> file_context Player.gd
  12 deps, 4 signals, used in 3 scenes, 8 importers

Health check: returns server status, version, and connection info.

> ping
  ✓ GodotIQ v0.1.0 — server healthy, 35 tools loaded

Complete asset inventory: find unused assets, missing references, by type.

> asset_registry
  124 assets: 48 textures, 32 audio, 3 unused, 1 missing ref

Recommend scale + position for model based on similar assets in scene.

> suggest_scale printer.glb --scene main.tscn
  Recommended: scale (1,1,1), position (4,0,2) based on 3 similar

Animation data: tracks, keyframes, length, looping, state machine transitions.

> animation_info Player.tscn
  3 animations, 24 keyframes, idle: 1.2s loop, run: 0.8s loop

Find animation problems: broken tracks, missing transitions, wrong loop settings.

> animation_audit
  ⚠ 1 broken track, 1 missing transition idle→jump

Batch scene editing with Ctrl+Z undo: move, rotate, scale, set_property, add_child, delete, duplicate, reparent.

> node_ops [{op: "move", node: "Shelf", position: [2,0,3]}]
  ✓ Shelf moved to (2, 0, 3) — Ctrl+Z to undo

Create multiple nodes using high-level patterns. One call = many nodes with undo.

> build_scene --grid {rows: 3, cols: 4, scene: "res://shelf.tscn"}
  ✓ 12 nodes created in grid pattern

Persist editor changes to disk.

> save_scene
  ✓ Saved main.tscn

Read, write, or patch GDScript files with convention validation.

> script_ops --read Player.gd
  class_name Player extends CharacterBody3D (42 lines)

Visual verification of game or editor viewport.

> screenshot --viewport editor --scale 0.25
  Captured 480×270 webp (12KB)

Editor 3D camera control: get position, reposition, focus on node.

> camera --action focus_node --node Player
  Camera focused on Player at (3, 1, 0)

Start or stop the Godot game from the editor.

> run --action play --scene main
  ✓ Game started (scene: main.tscn)

Query runtime property values. CHEAPER than screenshots — use first.

> state_inspect [{autoload: "EconomyManager", properties: ["balance"]}]
  EconomyManager.balance = 1500

Persistent property monitoring across game interactions.

> watch --action start --watches [{node: "Player", properties: ["position"]}]
  ✓ Watching Player.position (500ms interval)

Verify node property changes over time (proves movement/animation).

> verify_motion --node Player --duration 2.0
  Verdict: MOVING — position changed (0,1,0) → (3,1,2)

FPS, draw calls, memory, node count from running game.

> perf_snapshot
  60 FPS, 142 draw calls, 12.4MB texture memory

Editor state: open scenes, selected nodes, is game running, project path. Call FIRST.

> editor_context
  Scene: main.tscn, 3 selected, game: stopped

Live editor scene tree with transforms, scripts, groups, visibility.

> scene_tree --depth 3
  Main → World → Player (pos: 3,1,0) → Camera3D

Review what was changed — undo/redo state and action history.

> undo_history
  Last: "Move Shelf" — can undo: true, can redo: false

Check GDScript files for compilation/parse errors.

> check_errors --scope scene
  ✓ 0 errors in 12 scripts checked

Execute GDScript code. Last resort — prefer dedicated tools.

> exec "func run():
  return Engine.get_version_info()"
  {major: 4, minor: 3}

Filesystem operations within Godot project: list, read, write, move, delete, search, tree.

> file_ops --action list --path res://scenes --type scenes
  5 files: main.tscn, level1.tscn, menu.tscn...

Simulate player input: actions, keys, UI taps, waits.

> input [{actions: ["move_left"], hold_ms: 500}, {wait_ms: 200}]
  ✓ 2 commands executed, 0 errors

Map all UI elements: positions, text, interactivity, visibility.

> ui_map
  HUD → HealthBar (10,10) → Label "HP: 100" → Button "Shop"

Live pathfinding via NavigationServer3D. Can A reach B?

> nav_query --from_node Player --to_node Exit
  ✓ Reachable, distance: 28.4m, 12 waypoints