GodotIQ
@salvo10f
About GodotIQ
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.
Basic information
Config
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"
}
}
}
}Tools
35Health 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".
Overview
What is GodotIQ?
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.
How to use GodotIQ?
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.
Key features of GodotIQ
- Spatial intelligence —
scene_map,placement,spatial_auditunderstand 3D space, walls, navmesh, and empty slots - Signal flow tracing —
trace_flowshows what happens across files when an event fires - Code understanding —
dependency_graph,signal_map,impact_checkanalyse function calls and change impact - Smart placement —
placementfinds designated Marker3D slots first, then falls back to grid search with constraint solving - Runtime UI mapping —
ui_mapcaptures every button, label, and input with screen positions and touch target validation - Visual verification —
cameraandscreenshot(editor viewport) let the agent inspect changes - Convention enforcement —
validatechecks and auto-fixes GDScript conventions after edits - Project memory —
project_summaryandfile_contextre-prime agents after context compaction
Use cases of GodotIQ
- An AI agent placing a shelf in a 3D scene: it calls
placementto find a valid spot, thencamera+screenshotto visually confirm. - Debugging a signal: the agent calls
trace_flowto see the entire chain from “player accepts order” to outcome across multiple files. - Renaming a function: the agent calls
impact_checkto see what breaks anddependency_graphto find all callers. - Enforcing project conventions: after every edit, the agent calls
validateto automatically fix GDScript style issues. - Understanding a new project: the agent calls
project_summaryandfile_contextto quickly get an overview of architecture and key files.
FAQ from GodotIQ
What tools work without the Godot addon?
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.
How is GodotIQ different from other Godot MCPs?
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,
More Developer Tools MCP servers
Hello World MCP Server (Reference Extension)
anthropicsDesktop Extensions: One-click local MCP server installation in desktop apps
TalkToFigma
sonnylazuardiTalkToFigma: MCP integration between AI Agent (Cursor, Claude Code, Codex) and Figma, allowing Agentic AI to communicate with Figma for reading designs and modifying them programmatically.
Test
x1xhlolFULL Augment Code, Claude Code, Cluely, CodeBuddy, Comet, Cursor, Devin AI, Junie, Kiro, Leap.new, Lovable, Manus, NotionAI, Orchids.app, Perplexity, Poke, Qoder, Replit, Same.dev, Trae, Traycer AI, VSCode Agent, Warp.dev, Windsurf, Xcode, Z.ai Code, Dia & v0. (And other Open Sou
Burp Suite MCP Server Extension
PortSwiggerMCP Server for Burp
JetBrains MCP Proxy Server
JetBrainsA model context protocol server to work with JetBrains IDEs: IntelliJ, PyCharm, WebStorm, etc. Also, works with Android Studio
Comments