Configuration

GodotIQ is configured via a .godotiq.json file in your Godot project root (next to project.godot). All settings are optional — GodotIQ works with sensible defaults out of the box.

Configuration Reference

`disabled_tools`

Type: string[] · Default: []

List of tool names to disable entirely. Disabled tools will not appear in the MCP tool list. Useful for restricting what your AI can do.

{
  "disabled_tools": ["run", "node_ops", "exec"]
}

This prevents the AI from running the game, modifying scene nodes, or executing arbitrary GDScript.

`protected_files`

Type: string[] (glob patterns) · Default: []

Glob patterns for files that tools will refuse to modify. Read access still works — tools can analyze these files but won’t change them.

{
  "protected_files": ["addons/**", "*.import", "project.godot"]
}

`conventions`

Type: string[] · Default: []

Project-specific rules checked by the validate tool. Define naming conventions, architectural patterns, or code style requirements in plain language.

{
  "conventions": [
    "All autoloads must end with Manager",
    "Signals must be past tense (e.g., health_changed, not health_change)",
    "Scene files must be PascalCase",
    "Scripts must be snake_case"
  ]
}

Run validate to check your project against these rules.

`detail_level`

Type: "brief" | "normal" | "full" · Default: "normal"

Controls output verbosity for tools that support it.

Level	Description	Use case
`"brief"`	~80% fewer tokens	Large projects, routine operations
`"normal"`	Balanced detail	General development
`"full"`	Maximum detail	Debugging, investigation

{
  "detail_level": "brief"
}

`addon_port`

Type: number · Default: 6550

TCP port for the Godot addon bridge connection. Only relevant if using the Pro addon. Change if port 6550 conflicts with other software.

{
  "addon_port": 7000
}

`GODOTIQ_PROJECT_ROOT`

Type: Environment variable · Default: Auto-detected

Set this environment variable to explicitly specify your Godot project root directory (the directory containing project.godot). When set, GodotIQ skips auto-detection and uses this path directly.

This is particularly useful when:

Your MCP client runs from a different working directory than your Godot project
You want to use uv to run GodotIQ (see Installation for the uv config format)
Auto-detection fails because project.godot is in a non-standard location

export GODOTIQ_PROJECT_ROOT="/path/to/your/godot/project"

Or set it in your MCP client configuration’s env block (see Installation).

Example Configurations

Minimal (all defaults)

{}

No configuration needed — all 15 free tools work with default settings.

Safety-focused

{
  "disabled_tools": ["run", "node_ops", "exec", "script_ops"],
  "protected_files": ["addons/**", "project.godot", "*.import", "export_presets.cfg"]
}

Prevents the AI from running the game, modifying nodes, executing arbitrary GDScript, writing scripts, or changing critical project files.

Token-optimized

{
  "detail_level": "brief"
}

Reduces output size by ~80%. Recommended for large projects (100+ scenes) where you want faster, cheaper AI responses.

Full example

{
  "disabled_tools": ["input"],
  "protected_files": ["addons/**", "project.godot"],
  "conventions": [
    "All autoloads must end with Manager",
    "Signals must be past tense",
    "No more than 3 levels of scene nesting"
  ],
  "detail_level": "normal",
  "addon_port": 6550
}