GodotIQ MCP Server

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. 35 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 camera + screenshot → visually confirms result
  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
• Visual Verification — camera + screenshot (editor viewport). Agent looks at what it changed before moving on
• Convention Enforcement — validate checks and auto-fixes GDScript conventions after every edit
• Project Memory — project_summary, file_context. Agent re-primes instantly after context compaction

35 Tools in 9 Categories

17 tools work from filesystem alone (no Godot running). 18 tools need the lightweight GDScript addon.

Setup

1. Install GodotIQ

Direct install:

pip install godotiq

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

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

This copies:

• The GDScript addon files to /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"
      }
    }
  }
}

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 35 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/**", "*.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 (