GodotIQ

The only Godot MCP that understands your game, not just your files.

GodotIQ is a Model Context Protocol (MCP) server for Godot 4.x that gives AI agents (Claude Code, Cursor, Windsurf) spatial intelligence, code understanding, and runtime control. 38 tools across 9 categories — from smart object placement to signal flow tracing to automated UI mapping.

Other Godot MCPs are API wrappers. GodotIQ is an intelligence layer.

What It Does

Before GodotIQ:
  Agent: "I'll move this shelf to (2, 0, 0)"
  Result: Inside a wall. 10 iterations to fix.

After GodotIQ:
  Agent calls placement → knows empty slots, walls, navmesh, nearby objects
  Agent calls node_ops(validate=true) → validated placement, first try
  Agent calls verify_project_runs + read_debug_console → confirms Play starts cleanly
  Done.

Key Capabilities No Other MCP Has

• Spatial Intelligence — scene_map, placement, spatial_audit. Understands 3D space: distances, walls, navmesh, empty slots, scale consistency
• Signal Flow Tracing — trace_flow. "What happens when the player accepts an order?" → complete chain across 8 files with failure points
• Code Understanding — dependency_graph, signal_map, impact_check. Knows who calls who, what breaks if you change a function
• Smart Placement — placement finds designer-intended Marker3D slots first (95% confidence), falls back to grid search with constraint solving
• Runtime UI Mapping — ui_map. Maps every button, label, and input with screen positions, text content, touch target validation
• Debug Console Access — read_debug_console, verify_project_runs. Agents can read Godot errors directly instead of asking you to copy/paste the Debug window
• Visual Verification — camera + screenshot for visual-only checks when structured text inspection is insufficient
• Convention Enforcement — validate checks GDScript conventions after every edit
• Project Memory — project_summary, file_context. Agent re-primes instantly after context compaction

38 Tools — 24 Community, 14 Pro

GodotIQ ships 24 Community tools in the public package (MIT licensed) and 14 Pro tools in a separate private bundle (commercial license). Same install, same MCP — Pro tools activate automatically when a valid license key is present.

Community users get full results from the 24 free tools plus preview/teaser output from Pro tools. Pro users get full output from all 38 tools.

Pro activation

For an MCP client, the cross-platform way to set your key is the MCP server env block (see step 3). To set it directly in a shell:

# macOS / Linux (bash/zsh)
export GODOTIQ_LICENSE_KEY="pol_live_..."

# Windows (PowerShell)
$env:GODOTIQ_LICENSE_KEY = "pol_live_..."

On first startup with a valid key, GodotIQ auto-downloads the Pro bundle from pro.godotiq.com and caches it locally. Subsequent startups load from cache — Pro works fully offline once the bundle is cached.

No separate install step. No second package. Just set the env var.

When using uvx from an MCP client, put GODOTIQ_LICENSE_KEY in the MCP server env block. Exporting it in your shell is not enough if the MCP host launches uvx with its own environment.

Setup

1. Install GodotIQ

Direct install:

pip install "godotiq==0.5.16"

For AI clients (recommended): No manual install needed. Configure the MCP client to use uvx which auto-installs on first use (see step 3).

2. Install the Godot Addon

uvx godotiq install-addon /path/to/your/godot/project

If you installed GodotIQ with pip, godotiq install-addon /path/to/your/godot/project works too.

This copies:

• The GDScript addon files to /path/to/your/godot/project/addons/godotiq/
• GODOTIQ_RULES.md to the project root (AI assistant rules for Godot development)

Use --dry-run to preview what will be copied.

Then enable the addon in Godot via Project Settings → Plugins → GodotIQ → Enable.

The addon is pure GDScript (~500 lines, no compilation). It starts a WebSocket server on port 6007 for bidirectional communication with the MCP server.

3. Configure Your AI Client

Create .mcp.json in your Godot project root:

{
  "mcpServers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "/path/to/your/godot/project",
        "GODOTIQ_LICENSE_KEY": "YOUR_POLAR_LICENSE_KEY"
      }
    }
  }
}

For Community tier, omit the GODOTIQ_LICENSE_KEY line entirely. For Pro, keep it in this env block so the uvx environment can activate. This config is cross-platform: command is always uvx and the key lives in the JSON env block, so on Windows you never need to wrap the launch with the Unix-only env shim (which has no equivalent in cmd/PowerShell).

After setting or changing the key: fully restart your MCP client. MCP hosts launch the godotiq server once and keep it alive — a key added to .mcp.json (or your shell) only reaches a new server process. Reloading the chat window is usually NOT enough:

• Claude Code: exit the session and relaunch claude from the project directory
• Cursor / Windsurf: toggle the GodotIQ MCP server off/on in MCP settings, or restart the app
• Codex CLI: restart the CLI process

Then verify with the godotiq_ping tool (ask the assistant to call it): license must read "pro". If it still reads "community", the key is not reaching the server environment — re-check the env block placement above.

To verify the exact environment your MCP command sees:

# macOS / Linux (bash/zsh)
GODOTIQ_LICENSE_KEY="YOUR_POLAR_LICENSE_KEY" uvx godotiq auth status

# Windows (PowerShell)
$env:GODOTIQ_LICENSE_KEY = "YOUR_POLAR_LICENSE_KEY"; uvx godotiq auth status

If activation state gets stuck after revoking seats or changing machines:

uvx godotiq auth reset --yes

Then launch Claude Code from your project directory:

cd /path/to/your/godot/project
claude

Claude Code reads .mcp.json automatically and connects to GodotIQ with 38 tools available.

4. (Optional) Project Configuration

Create .godotiq.json in your Godot project root for project-specific settings:

{
  "version": 2,
  "project": {
    "name": "My Game",
    "engine": "godot_4",
    "type": "3d"
  },
  "disabled_tools": [],
  "protected_files": ["project.godot", ".godot/**", ".godotiq/**", "*.import"],
  "conventions": {
    "class_name_suffix": "Class",
    "signal_bus": "Events",
    "require_type_hints": true
  },
  "asset_origins": {
    "meshy": {
      "path_patterns": ["assets/models/printers/**"],
      "default_scale": [0.3, 0.3, 0.3]
    }
  },
  "server": {
    "default_detail": "normal",
    "screenshot_default_scale": 0.25
  }
}

Architecture

godotiq/
├── src/godotiq/
│   ├── server.py              # MCP server (FastMCP, stdio transport)
│   ├── config.py              # .godotiq.json configuration loader
│   ├── session.py             # Project session management
│   ├── parsers/               # .tscn, .gd file parsers (zero external deps)
│   │   ├── tscn_parser.py     # Godot scene format parser
│   │   ├── gd_parser.py       # GDScript parser (signals, deps, functions)
│   │   ├── scene_resolver.py  # Instance expansion, world-space transforms
│   │   └── project_index.py   # Full project scan, cross-reference maps
│   ├── cache/                 # Hash-based file cache
│   └── tools/                 # 9 categories, 38 tools
│       ├── bridge/            # Runtime: screenshot, run, input, node_ops, exec...
│       ├── spatial/           # scene_map, placement, spatial_audit
│       ├── code/              # dependency_graph, signal_map, impact_check, validate
│       ├── animation/         # animation_info, animation_audit
│       ├── flow/              # trace_flow
│       ├── assets/            # asset_registry, suggest_scale
│       ├── memory/            # project_summary, file_context
│       ├── ui/                # ui_map
│       └── navigation/        # nav_query
├── godot-addon/
│   └── addons/godotiq/
│       ├── plugin.cfg
│       ├── godotiq_plugin.gd      # EditorPlugin entry point
│       ├── godotiq_server.gd      # WebSocket server (editor-side)
│       ├── godotiq_runtime.gd     # Autoload (game-side, screenshots + input)
│       └── godotiq_debugger.gd    # EditorDebuggerPlugin (error capture)
├── tests/                     # 1400+ automated tests
│   ├── fixtures/              # Real .tscn/.gd files from Godot projects
│   └── test_*/                # Test suites per category
└── .godotiq.json              # Example project configuration

Communication Stack

AI Agent ←(stdio)→ Python MCP Server ←(WebSocket:6007)→ GDScript Addon in Godot Editor
                   (intelligence layer)                    (runtime bridge)
                                                              ↕
                                                    EngineDebugger (IPC)
                                                              ↕
                                                    Running Game (autoload)

• Python → Editor: WebSocket for bidirectional real-time communication
• Editor → Game: EngineDebugger native IPC for screenshots, input simulation, state inspection
• Intelligence layer: All parsing, spatial reasoning, dependency analysis, convention validation runs in Python — works without Godot open

Three-Layer Parser Architecture

1. Layer 1 — Raw Parser: Reads single .tscn/.gd file, extracts structure
2. Layer 2 — Scene Resolver: Expands instances recursively, calculates world-space transforms
3. Layer 3 — Project Index: Scans all files, builds cross-reference maps (signal wiring, autoloads, asset usage)

Token Optimization

Every tool accepts detail: "brief" | "normal" | "full":

• brief → 5-15 lines, key facts only. Use for routine checks.
• normal → Default. Structured data for most operations.
• full → Complete dump with metadata. Use for deep debugging.

This cuts response sizes 50-80% for routine operations, saving context window space.

Development

# Run all tests
pytest tests/ -v

# Run specific category
pytest tests/test_tools/ -v
pytest tests/test_parsers/ -v

# Run with coverage
pytest tests/ --cov=godotiq -v

Test Stats

• 1400+ automated tests
• Real .tscn/.gd fixtures from production Godot projects
• Parser tests, tool tests, integration tests, config tests, Pro bundle lifecycle tests

Comparison

Recent Changes

See CHANGELOG.md for full history.

0.4.1 — Fix addon version sync; improved Pro diagnostics in godotiq_ping

License

• Public package + Godot addon: MIT
• Pro bundle: Commercial license — see godotiq.com/pro

mcp-name: io.github.salvo10f/godotiq