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.

Setup

1. Install GodotIQ:

   pip install godotiq

2. Add the MCP server:

   claude mcp add godotiq -- godotiq --project /path/to/your/godot/project

   Replace the path with your Godot project root (the directory containing project.godot). Alternatively, use uv and set GODOTIQ_PROJECT_ROOT — see Installation for details.

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 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?” → scene_map
• “What would break if I rename PlayerManager?” → impact_check
• “Place torches along the corridor walls” → placement
• “Why is the health bar not updating?” → trace_flow + 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: project_summary → trace_flow → signal_map
• Safe refactor: impact_check → signal_map → make changes → validate
• Level review: scene_map → spatial_audit → placement (for fixes)

Project-Scoped vs Global

If you work on multiple Godot projects, add GodotIQ to each project separately:

# In project A's directory
claude mcp add godotiq -- godotiq --project /path/to/project-a

# In project B's directory
claude mcp add godotiq -- godotiq --project /path/to/project-b

Claude Code automatically uses the right server based on your working directory.

Advanced Configuration

Custom Config File

Point GodotIQ to a custom config file:

claude mcp add godotiq -- godotiq --project /path/to/project --config /path/to/.godotiq.json

Bridge Port

If you’re using the Pro addon and the default port (6550) conflicts with something:

claude mcp add godotiq -- godotiq --project /path/to/project --bridge-port 6551

Make sure to update the 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 (screenshot, run, node_ops, etc.) require the Godot addon to be installed and Godot to be running. Free tools work without the addon.

Installation Full installation guide with all client options.

Workflows Common workflow patterns for AI-assisted game development.