Claude Code

Claude Code is the recommended client for GodotIQ. It runs in your terminal alongside your editor, has native MCP support, and handles large tool outputs well.

Running godotiq install-addon automatically creates CLAUDE.md with development rules for this client. No manual configuration needed.

Setup

1. Install GodotIQ:

   pip install godotiq

2. Add the MCP server. Toggle Community or Pro and copy the snippet:

   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.

   Swap in your project path (placeholder: <REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>). For Pro, paste your license key in place of the GODOTIQ-XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX token. uvx auto-installs godotiq on first use.

3. Verify the connection:

   Open Claude Code and ask: “Ping GodotIQ”. It should confirm the server is running.

Tips for Claude Code

Start Every Session with Context

Claude Code’s context window compresses over long sessions. Start each conversation by asking:

“Use godotiq_project_summary to understand this project, then help me with…”

This gives Claude full project awareness (architecture, file relationships, conventions) before you start working.

Use Natural Language

You don’t need to specify tool names. GodotIQ tools are designed to be invoked naturally:

• “What’s the layout of my dungeon level?” → godotiq_scene_map
• “What would break if I rename PlayerManager?” → godotiq_impact_check
• “Place torches along the corridor walls” → godotiq_placement
• “Why is the health bar not updating?” → godotiq_trace_flow + godotiq_signal_map

Claude will select the right tool based on your question.

Extended Thinking for Complex Tasks

For multi-step tasks like debugging or refactoring, Claude Code’s extended thinking mode helps it plan a tool chain before executing:

“Think step by step about why the enemy AI gets stuck at the bridge, then trace the flow to find the issue.”

This often produces better results than a single-shot question because Claude can plan which tools to call in what order.

Multi-Tool Chains

Claude Code can call multiple GodotIQ tools in sequence within a single conversation. Common patterns:

• Debug flow: godotiq_project_summary → godotiq_trace_flow → godotiq_signal_map
• Safe refactor: godotiq_impact_check → godotiq_signal_map → make changes → godotiq_validate
• Level review: godotiq_scene_map → godotiq_spatial_audit → godotiq_placement (for fixes)

Project-Scoped vs Global

If you work on multiple Godot projects, add GodotIQ to each project separately: create a .mcp.json in each project root with the appropriate GODOTIQ_PROJECT_ROOT path. Claude Code automatically uses the right server based on your working directory.

Activate Pro

Toggle Pro in the snippet above, paste your license key, and restart Claude Code. The tier toggle keeps every other field identical to Community — only the GODOTIQ_LICENSE_KEY env is added.

If activation doesn’t take, see Manage to deactivate old devices or Troubleshooting.

Advanced Configuration

Bridge Port

If the default WebSocket port (6007) conflicts with something, update the addon_port in your .godotiq.json and the Godot addon settings to match.

Tip

See the Configuration Reference for all available .godotiq.json options and the Addon Reference for bridge setup.

Troubleshooting

”MCP server not responding”

1. Check that GodotIQ is installed: pip show godotiq
2. Verify the project path exists and contains project.godot
3. Restart Claude Code: claude (exit and re-enter)

“Tool not found”

Make sure you’re using the latest version: pip install --upgrade godotiq

Bridge tools not working

Bridge tools (godotiq_screenshot, godotiq_run, godotiq_node_ops, etc.) are free but require the GodotIQ addon installed in your Godot project and the editor to be running. The addon communicates via WebSocket on port 6007.

Bought Pro?

1. Toggle Pro in the snippet above and paste your license key.
2. Restart Claude Code.
3. Run godotiq auth status — expected: license: pro (active).
4. If activation fails, visit Manage or Troubleshooting. Or email [email protected].

Installation Full installation guide with all client options.

Workflows Common workflow patterns for AI-assisted game development.