@salvo10f
Basic information
The intelligent MCP server for AI-assisted Godot 4 development. 35 tools for spatial intelligence, code understanding, flow tracing, and visual debugging. 22 free, full suite $19. Visit godotiq.com to see more.
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"godotiq": {
"command": "uvx",
"args": [
"godotiq"
],
"env": {
"GODOTIQ_PROJECT_ROOT": "/path/to/your/godot/project"
}
}
}
}Health check tool. Returns server status and version. Args: detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Call FIRST in every session. Architecture, autoloads, conventions, file counts. Replaces manual project exploration — one call gives full context. Use detail="brief" for counts only. Args: detail: "brief" (counts + autoload names), "normal" (+ architecture), "full" (+ scene structure, signal health).
Call BEFORE editing any file. Returns public API, dependencies, signals, who imports this file, scene usage. Without this you risk breaking callers. DO NOT read .gd/.tscn files directly — this gives structured cross-referenced data. Args: file: Path to file (res:// or relative). Works for .gd scripts and .tscn scenes. detail: "brief" (public API only), "normal" (+ deps, signals, safety), "full".
Complete dependency graph: what this file emits, who listens, what it imports, who imports it, impact rating. Call before refactoring function signatures or renaming signals. DO NOT grep the codebase — this traces the full graph in one call. Args: file: Path to .gd file (res:// or relative). depth: How many levels deep to trace (1 = direct deps only, 2 = deps of deps). detail: "brief" (signal names + refs only), "normal" (+ listeners, autoloads), "full" (+ depth_trace always).
Project-wide signal wiring: who emits, who listens, orphan/missing signals. DO NOT grep for .connect() calls — this traces the complete signal graph in one call. Use find="orphans" to find dead signals, "missing" to find typos. Args: scope: "all" for entire project, "autoloads" for autoload scripts only, or "file:res://path.gd" for a single file's signals. find: "all" (everything), "orphans" (emitted but no listeners), "busiest" (most connected), "missing" (emitted but never defined — likely typos). detail: "brief" (orphans + missing only — the actionable items), "normal" (default), "full".
Predict what breaks BEFORE making a change. Returns affected files, callers, risk level, and safe alternatives. Call before renaming, removing, or changing any function/signal/class signature. DO NOT manually search for callers — this finds them all. Args: file: Path to .gd file being modified. action: "modify_function", "rename_signal", "add_parameter", "remove_function", "change_return_type", "rename_class". target: The function/signal/class being changed. change_description: Free-text description of the intended change (used in safe_alternative suggestions). detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Convention check: missing type hints, missing class_name, orphan signals, naming violations. Run after every code change. Use on "project" for full scan or target a single file. Args: target: "project" for full scan, or path to a specific .gd file. detail: "brief" (severity counts only), "normal" (+ issue list), "full".
Spatial understanding of a .tscn scene: positions, distances, directions, bounds. ALWAYS call before placing or moving 3D objects — never guess positions. DO NOT read .tscn files directly — they are unreadable resource format. Use focus + radius to zoom into an area. Args: scene: Path to .tscn file (res:// or relative). focus: Node name or path to center the view on. Returns nearby nodes sorted by distance. radius: Distance filter around focus node (meters, default 5.0). Only used with focus. include: List of node types or groups to include (e.g. ["MeshInstance3D", "enemies"]). detail: "brief" (name/type/position only), "normal" (+ groups, scripts, bounds), "full" (+ properties, distance matrix).
Automated 3D scene linter: floating objects, scale mismatches, z-fighting, overlapping instances, extreme positions. Run on any scene to catch spatial issues before they become visual bugs. Use detail="brief" for only real problems. Args: scene: Path to .tscn file (res:// or relative). checks: Specific checks to run (default all 6): "floating_objects", "scale_mismatch", "z_fighting", "empty_markers", "overlapping", "extreme_positions". min_severity: Minimum severity: "warning" (default, filters info), "info" (everything), "critical". detail: "brief" (critical + warning only), "normal" (excludes cosmetic z-fighting/overlapping), "full" (everything).
Find safe placement positions for new objects. DO NOT guess positions or manually calculate coordinates. Checks Marker3D slots first (designer-intended spots, highest confidence), then grid-searches nearby space with wall/overlap validation. Returns up to 3 suggestions with confidence scores. Args: scene: Scene file path (.tscn). Uses project main scene if empty. near: Node name to place near (e.g. "PrinterSlot_P3"). near_position: [x, y, z] coordinates to place near (alternative to 'near'). object_type: Semantic type hint (e.g. "printer", "shelf") — finds similar objects for scale/rotation reference. constraints: {on_floor: bool, min_wall_distance: float, min_object_distance: float, face_direction: str, marker_group: str}. max_suggestions: Maximum number of suggestions (default 3). detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Complete asset inventory: find unused assets, missing references, assets by type. Use to audit project assets and clean up bloat. Args: category: "all", "models", "textures", "audio", "scenes", "scripts", etc. check_usage: Check which assets are actually used in scenes (default true). detail: "brief" (counts only), "normal" (counts + top 20 unused), "full" (everything). path_filter: Filter assets by path substring (e.g. "kenney_furniturekit"). max_results: Max number of assets to return (0 = no limit).
Recommend scale + position for a model based on similar assets in the scene. Never guess scales — this analyzes existing objects and suggests matching values. Respects asset_origins from .godotiq.json. Args: scene: Path to .tscn file (res:// or relative). model: Model asset path (res://). Omit for reference mode (returns scale stats for matching nodes). near_node: Node name to suggest position near. intended_use: Semantic hint (e.g. "printer", "shelf"). Required when model is omitted. detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Animation data for any node: tracks, keyframes, length, looping, state machine transitions. Use to understand animation setup before modifying. Args: scene: Path to .tscn file (res:// or relative). node: AnimationPlayer name to filter on (shows all if omitted). detail: "brief" (animation names + lengths), "normal" (+ tracks, transitions), "full" (+ keyframe data).
Find animation problems: broken tracks, missing transitions, wrong loop settings, unreferenced animations. Run before shipping to catch animation bugs. Args: scope: "all" (scan entire project) or "scene" (single scene). scene: Path to .tscn file when scope="scene". detail: "brief" (severity counts only), "normal" (+ issue list), "full".
Visual verification of the game or editor viewport. Use scale=0.25, quality=0.3 for token-efficient checks. Prefer state_inspect for data — use screenshot only when you need visual confirmation. Args: viewport: "game" (requires running game) or "editor" (3D editor, no game needed). scale: Image scale (0.0-1.0). Default 0.25 for token efficiency. format: "webp" (default, smallest), "png", "jpg". quality: Encoding quality (0.1-1.0). Use 0.3 for routine checks, 0.8 for detail. camera_position: [x, y, z] — Editor only. Move camera before capture. camera_target: [x, y, z] — Editor only. Camera looks at this point. detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Start or stop the Godot game. Must call play before using any game-side tools (state_inspect, screenshot, input, nav_query, watch, ui_map). Waits for confirmed startup. Args: action: "play" to start, "stop" to halt the running game. scene: "main" (default), "current", or a res:// path. detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
FPS, draw calls, memory, node count from the running game. Use for performance profiling. Game must be running. Args: detail: "brief" (fps + draw_calls only), "normal" (all metrics), "full".
Call FIRST alongside project_summary. Returns editor state: open scenes, selected nodes, is game running, project path. Essential for understanding current context before any operations. Args: detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Live editor scene tree — actual state with transforms, scripts, groups, visibility. Unlike scene_map (reads .tscn from disk), this reads the editor's live state. Call BEFORE node_ops to see current node names and paths. Args: root: Node path to start from (e.g. "Level/Enemies"). Empty = scene root. depth: Max tree depth (1-10, default 3). filter_type: Only include nodes of this type (e.g. "MeshInstance3D"). include: Data fields per node. Default: ["transform","script","groups","visibility"]. detail: "brief" (names + types, max 20 nodes), "normal" (default), "full" (+ script paths, signals).
Core scene editing tool. Batch operations with Ctrl+Z undo: move, rotate, scale, set_property, add_child, delete, duplicate, reparent. All ops in one call = one undo action. ALWAYS add validate:true for spatial operations (move/scale/add_child) to prevent placing objects inside walls or on top of each other. If ANY validated op is BLOCKED, the entire batch is rejected (atomic). Args: operations: List of operation dicts, each with 'op' key. Max 50 per call. scene: Optional .tscn path for spatial validation (auto-detects main scene if omitted). detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Read, write, or patch GDScript files with convention validation. ALWAYS prefer this over raw file writes for .gd files. Patch mode (find-and-replace) is safest — only changes what you specify. Args: op: "read", "write", "patch", or "create". path: File path (res:// or relative). content: File content for write/create. patches: List of {search, replace} dicts for patch mode. validate_before_write: Run convention checks before writing (default true). auto_fix: Auto-fix detected issues. dry_run: Validate without writing. detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Filesystem operations within the Godot project: list, read, write, move, delete, search, tree, uid_to_path, path_to_uid, rename (with reference updates). Respects protected files from .godotiq.json. For .gd files, prefer script_ops instead. Args: op: "list", "read", "write", "move", "delete", "search", "tree", "uid_to_path", "path_to_uid", "rename". path: Target path (res:// or relative). query: Search query (for search) or uid string (for uid_to_path). filter: Type filter ("all", "scenes", "scripts", "images", "audio", etc.). recursive: Include subdirectories in list. context_lines: Context around search matches (default 2). max_depth: Tree depth (default 3). show_sizes: Include file sizes in tree. content: File content for write. For rename: "false" to skip ref updates. destination: Destination for move/rename. detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Simulate player input in the running game: actions, keys, UI taps, waits. Use after ui_map to know what's on screen. Supports signal verification and side-effect tracking. Game must be running. Args: commands: Sequential list: {"actions": ["move_left"], "hold_ms": 500}, {"wait_ms": 200}, {"key": "space"}, {"tap": "AcceptButton"}. track_side_effects: Monitor autoload state changes before/after. continue_on_error: Keep going if a command fails. wait_for: Signal to wait for (e.g. "signal:OrderManager.order_accepted"). wait_for_timeout_ms: Timeout for wait_for in ms. detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Execute GDScript code. Last resort — prefer dedicated tools (node_ops, script_ops, state_inspect) over exec. Code MUST contain 'func run():'. In game context use Engine.get_main_loop() instead of get_tree(). Args: code: GDScript with 'func run():'. Return value is stringified. context: "game" (sandbox, game must run) or "editor" (full EditorInterface access, no game needed). timeout_ms: Max execution time in ms (default 5000). detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Query runtime property values. CHEAPER than screenshots for checking state — use this first. Supports autoload lookup by name, node paths, nested properties, method calls like 'pending_orders.size()'. Game must be running. Args: queries: [{node: "/root/Main/Player", properties: ["health", "position"]}] or [{autoload: "EconomyManager", properties: ["balance"]}]. detail: "brief" (values only, no metadata), "normal" (default), "full" (+ class name, node path).
Live pathfinding via NavigationServer3D. "Can A reach B?" Returns path, distance, reachability, navmesh status. Game must be running. Args: from_node: Source node name (uses its global_position). to_node: Target node name. from_position: [x, y, z] alternative to from_node. to_position: [x, y, z] alternative to to_node. optimize: Optimize path (default true). detail: "brief" (reachable + distance only), "normal" (+ path points), "full".
Persistent property monitoring. Start watching, then read accumulated changes over time. Use for tracking values across game interactions. Game must be running. Args: action: "start", "stop", "read", "clear". watches: For "start": [{node: "/root/Main/Player", properties: ["health", "position"]}]. sample_interval_ms: Sampling interval (default 500, min 50). detail: "brief" (last 10 events only), "normal" (default), "full" (all events + timestamps).
Review what was changed. Shows undo/redo state and recent GodotIQ action history. Call after node_ops to verify changes. Editor-side — no game needed. Args: detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Persist editor changes to disk. Call after node_ops or any scene modifications. In-place save. Editor-side — no game needed. Args: detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Editor 3D camera control: get current position, reposition, or focus on a node. Editor-side — no game needed. Args: action: "get_position", "look_at", or "focus_node". position: [x, y, z] for look_at — camera position. target: [x, y, z] for look_at — camera target. node: Node name for focus_node. detail: Output verbosity — "brief" (summary), "normal" (default), or "full" (everything).
Map all UI elements on screen: positions, text, interactivity, visibility. Call BEFORE godotiq_input to know what buttons/controls exist. Game must be running. Args: root: Root node name (e.g. "GameHUD"). Empty = entire UI tree. include_invisible: Include hidden elements (default false). max_depth: Tree traversal depth (default 10). detail: "brief" (interactive elements only + count), "normal" (default), "full" (+ modulate, mouse_filter, script).
Create multiple nodes in a scene using high-level patterns. One call = many nodes with Ctrl+Z undo. Use INSTEAD of repeated node_ops add_child calls. Modes (exactly one required): grid: Place nodes in a rows x cols grid. Keys: rows (int), cols (int), spacing (float, default 1.0), scene (res:// path), type (node type). line: Place nodes along a polyline path. Keys: points (list of [x,y,z]), spacing (float, default 1.0), scene, type. scatter: Place nodes at explicit positions. Keys: items (list of {scene, position, rotation, scale}). nodes: Explicit node list. Each dict: {type, name, position, rotation, scale, properties, scene}. Args: target_scene: .tscn path for context (auto-detects if empty). parent: Parent node path (e.g. "Level/Props"). Empty = scene root. detail: Output verbosity -- "brief" (default), "normal", "full". grid: Grid pattern config. line: Line pattern config. scatter: Scatter placement config. nodes: Explicit node definitions.
Check GDScript files for compilation/parse errors. Args: scope: "scene" (current scene + autoloads), "project" (all .gd files), or "res://path/to/script.gd" (single file)
Verify a node property changes over time (proves movement/animation). Takes two state_inspect snapshots separated by a sleep and compares values. Use instead of screenshots to verify motion. Game must be running. Args: node: Node path or name to inspect. property_name: Property to monitor (default "position"). duration: Seconds to wait between snapshots (default 2.0). detail: Output verbosity — "brief", "normal", or "full".
Trace execution flow from a function or signal through the entire codebase. "What happens when X is called?" Returns the chain of calls, signal emissions, and failure points. DO NOT manually trace call chains — this does it automatically. Args: trigger: Exact function or signal name to trace (e.g. "start_print_job", "order_completed"). depth: Max recursion depth (default 10). detail: "brief" (steps only — file + function), "normal" (+ line numbers, failure points), "full".
GodotIQ is a Model Context Protocol (MCP) server for Godot 4.x that provides AI agents (Claude Code, Cursor, Windsurf) with spatial intelligence, code understanding, and runtime control through 35 tools across 9 categories. It is designed for Godot developers who want AI assistance that understands a game’s 3D space, signal wiring, and project architecture, not just raw files.
Install the Python package (pip install godotiq or use uvx to auto-install), then run godotiq install-addon /path/to/project to copy the GDScript addon and enable it in Godot. Configure your AI client by adding a .mcp.json file with "command": "uvx" and "args": ["godotiq"], setting GODOTIQ_PROJECT_ROOT to your project path. Optionally create a .godotiq.json for project-specific settings. 17 tools work from the filesystem alone (no Godot running); 18 require the addon.
scene_map, placement, spatial_audit understand 3D space, walls, navmesh, and empty slotstrace_flow shows what happens across files when an event firesdependency_graph, signal_map, impact_check analyse function calls and change impactplacement finds designated Marker3D slots first, then falls back to grid search with constraint solvingui_map captures every button, label, and input with screen positions and touch target validationcamera and screenshot (editor viewport) let the agent inspect changesvalidate checks and auto-fixes GDScript conventions after editsproject_summary and file_context re-prime agents after context compactionplacement to find a valid spot, then camera + screenshot to visually confirm.trace_flow to see the entire chain from “player accepts order” to outcome across multiple files.impact_check to see what breaks and dependency_graph to find all callers.validate to automatically fix GDScript style issues.project_summary and file_context to quickly get an overview of architecture and key files.17 tools work from the filesystem alone (no Godot running). These include all Code, Animation, Flow, Assets, and Memory tools, plus the `validate` tool. The other 18 tools require the lightweight GDScript addon to be enabled in the Godot editor.
GodotIQ provides spatial intelligence, signal flow tracing, code understanding, convention validation, project memory, UI mapping, visual verification, and token optimisation (three detail levels). Other MCPs lack these capabilities; for example, GDAI (27 tools,
ZeroBeacon.ai — Collision-proof commerce router for AI agents. 1000 MCP tools: commerce, trust, billing, sovereign ID + everyday tools. LIVE.
MCP server that lets Claude Code, Cursor or Codex ask you for API keys on a local page and write them to .env. The agent only ever sees key names.
Agent-Native Terminal
Give your AI agent the ability to see any webpage. Capture screenshots from Claude, Cursor, or any MCP client. Supports full-page, dark mode, mobile emulation, OG image generation, base64 output, custom viewport, ad bloc
Catch intent conflicts before code conflicts. The open-source coordination protocol for coding agents, built above Git.
Comments