Installation

Prerequisites

Before installing GodotIQ, ensure you have:

• Python 3.10, 3.11, 3.12, 3.13 (python.org/downloads)
• Godot 4.x (any 4.x release) (godotengine.org)
• An MCP-compatible AI client (Claude Code, Codex, Cursor, Windsurf, VS Code Copilot, or any MCP client)

Install GodotIQ

1. Install via pip:

   pip install godotiq

   This installs the Community edition with 22 free tools for reading, writing, executing, and querying your Godot project. Only 4 runtime dependencies (mcp, websockets, httpx, platformdirs). Available on PyPI.

2. Configure your MCP client — pick your client in the tabs below.

3. Verify the connection by asking your AI to use the godotiq_ping tool, or simply ask: “Ping GodotIQ”. It should confirm the server is running.

Configure Your MCP Client

Pick your client in the tabs, toggle Community or Pro, and copy the snippet. Swap in your project path (the placeholder is <REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>); for Pro, replace the license-key token with the key from your purchase email.

Claude Code Codex Cursor Windsurf VS Code

Community Pro

~/.claude/mcp.json or via CLI bash Copy

claude mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> uvx godotiq

~/.claude/mcp.json or via CLI bash Copy

claude mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> GODOTIQ_LICENSE_KEY=GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX uvx godotiq

Option A — CLI bash Copy

codex mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> uvx godotiq

Option B — ~/.codex/config.toml toml Copy

[mcp_servers.godotiq]
command = "uvx"
args = ["godotiq"]

[mcp_servers.godotiq.env]
GODOTIQ_PROJECT_ROOT = "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"

Option A — CLI bash Copy

codex mcp add godotiq -- env GODOTIQ_PROJECT_ROOT=<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH> GODOTIQ_LICENSE_KEY=GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX uvx godotiq

Option B — ~/.codex/config.toml toml Copy

[mcp_servers.godotiq]
command = "uvx"
args = ["godotiq"]

[mcp_servers.godotiq.env]
GODOTIQ_PROJECT_ROOT = "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
GODOTIQ_LICENSE_KEY = "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

.cursor/mcp.json json Copy

{
  "mcpServers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
      }
    }
  }
}

.cursor/mcp.json json Copy

{
  "mcpServers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>",
        "GODOTIQ_LICENSE_KEY": "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    }
  }
}

~/.codeium/windsurf/mcp_config.json json Copy

{
  "mcpServers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
      }
    }
  }
}

~/.codeium/windsurf/mcp_config.json json Copy

{
  "mcpServers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>",
        "GODOTIQ_LICENSE_KEY": "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    }
  }
}

.vscode/settings.json json Copy

{
  "mcp.servers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>"
      }
    }
  }
}

.vscode/settings.json json Copy

{
  "mcp.servers": {
    "godotiq": {
      "command": "uvx",
      "args": ["godotiq"],
      "env": {
        "GODOTIQ_PROJECT_ROOT": "<REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>",
        "GODOTIQ_LICENSE_KEY": "GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
      }
    }
  }
}

macOS/Linux: pwd · Windows PowerShell: (Get-Location).Path

Omit GODOTIQ_LICENSE_KEY to use Community. Add your license key to unlock the 14 Pro intelligence tools.

Tip

Install the Godot Addon. 18 of the 22 free tools require the Godot addon for live editor/game interaction. Install it with:

godotiq install-addon <REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>

This automatically configures rules for every major AI client:

• CLAUDE.md (Claude Code)
• AGENTS.md (OpenAI Codex)
• .cursorrules (Cursor)
• .windsurfrules (Windsurf)
• .github/copilot-instructions.md (GitHub Copilot)

No manual configuration needed — one command sets up all clients.

Then enable the addon in Godot: Project Settings → Plugins → GodotIQ → Enable. See the Addon Reference for details.

Note

Pro tools (14) add the intelligence layer: spatial analysis, code understanding, flow tracing, project memory, asset management, animation auditing, and visual inspection. All Pro tools are filesystem-only and don’t require the addon. Get GodotIQ Pro for $19.

Activate Pro

After purchasing GodotIQ Pro, toggle the Pro switch in the snippet above and paste your license key in place of GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. The config stays identical to Community apart from the added GODOTIQ_LICENSE_KEY env.

Your license key arrives by email. This unlocks all 14 Pro intelligence tools. Without a key, the 22 free tools work normally; Pro-only tools return preview/upgrade output until a valid Pro license is configured.

Verify activation

godotiq auth status

If the status prints license: pro (active), you’re wired up. Head to /manage/ if anything looks wrong.

How Pro activation works

GodotIQ always installs as a single public package. When GODOTIQ_LICENSE_KEY is present and valid, GodotIQ automatically downloads the private Pro bundle on first use and caches it locally. There is no separate pip install for Pro.

Community users still see the 22 free tools. Pro-only tools return preview/upgrade output until a valid Pro license is configured.

After the bundle has been downloaded once, Pro continues working from the local cache. If you are offline on the first Pro run after installing or upgrading, GodotIQ falls back to Community mode for that session.

Troubleshooting

If something’s wrong, see /troubleshooting/ or email [email protected].

Next Steps

Quickstart Try five prompts to explore your Godot project with AI.

Configuration Customize GodotIQ behavior with .godotiq.json.