Configuration File

GodotIQ is configured via a .godotiq.json file in your Godot project root (next to project.godot). All keys are optional. An empty {} or no file at all uses sensible defaults.

For practical examples and common configurations, see Configuration.

JSON Schema

.godotiq.json

{
  "disabled_tools": string[],
  "protected_files": string[],
  "conventions": string[],
  "detail_level": "brief" | "normal" | "full",
  "addon_port": number
}

---

disabled_tools

Type: string[] · Default: []

Disables tools by name. Disabled tools are removed from the MCP tool list entirely. The AI client won’t see them and can’t invoke them.

Accepted values

Any registered tool name. The full list of tool names:

Category	Tool names
Bridge (FREE)	godotiq_ping, godotiq_editor_context, godotiq_scene_tree, godotiq_node_ops, godotiq_build_scene, godotiq_save_scene, godotiq_script_ops, godotiq_file_ops, godotiq_exec, godotiq_run, godotiq_input, godotiq_screenshot, godotiq_camera, godotiq_state_inspect, godotiq_perf_snapshot, godotiq_watch, godotiq_undo_history, godotiq_check_errors, godotiq_verify_motion
Spatial (PRO)	godotiq_scene_map, godotiq_spatial_audit, godotiq_placement
Code (PRO)	godotiq_dependency_graph, godotiq_validate, godotiq_signal_map, godotiq_impact_check
Animation	godotiq_animation_info (FREE), godotiq_animation_audit (PRO)
Flow (PRO)	godotiq_trace_flow
Assets (PRO)	godotiq_asset_registry, godotiq_suggest_scale
Memory (PRO)	godotiq_project_summary, godotiq_file_context
UI (FREE)	godotiq_ui_map
Navigation (FREE)	godotiq_nav_query

Validation rules

• Unknown tool names are silently ignored (no error, no effect).
• Tool names are case-sensitive and must match exactly.
• An empty array [] is equivalent to omitting the key.

Example

.godotiq.json

{
  "disabled_tools": ["godotiq_run", "godotiq_node_ops", "godotiq_input", "godotiq_exec"]
}

Prevents the AI from running the game, editing nodes, simulating input, or executing arbitrary code. Useful for safety in production projects.

---

protected_files

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

Glob patterns for files that tools will refuse to modify. Protected files can still be read and analyzed. Only writes are blocked.

Glob syntax

Patterns follow Python’s fnmatch rules:

Pattern	Matches
*.import	All .import files in the root
addons/**	Everything in the addons/ directory (recursive)
project.godot	The project file exactly
scenes/ui/*.tscn	All .tscn files in scenes/ui/
**/*.tres	All .tres files anywhere in the project

Validation rules

• Patterns are matched relative to the Godot project root.
• Multiple patterns are OR’d. A file matching any pattern is protected.
• Invalid glob syntax is silently ignored.
• An empty array [] is equivalent to omitting the key.

Example

.godotiq.json

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

---

conventions

Type: string[] · Default: []

Project-specific rules written in plain language. These are checked by the godotiq_validate tool when run.

How it works

1. Define conventions as human-readable strings.
2. Run the godotiq_validate tool (or ask the AI to “validate my project”).
3. GodotIQ checks each convention against the project and reports violations.

Validation rules

• Each string should describe one rule.
• There is no maximum count, but each convention adds processing time to godotiq_validate.
• Empty strings are ignored.
• Conventions are not enforced automatically. They are only checked when godotiq_validate is invoked.

Example

.godotiq.json

{
  "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",
    "No more than 3 levels of scene nesting"
  ]
}

---

detail_level

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

Controls output verbosity for tools that support the detail parameter. This sets the project-wide default. Individual tool calls can override it with an explicit detail argument.

Levels

Level	Token reduction	Best for
"brief"	~80% fewer tokens	Large projects (100+ scenes), routine operations, cost-sensitive workflows
"normal"	Baseline	General development
"full"	~40% more tokens	Debugging, investigation, unfamiliar codebases

Tools that support detail

godotiq_scene_map, godotiq_spatial_audit, godotiq_dependency_graph, godotiq_signal_map, godotiq_impact_check, godotiq_validate, godotiq_trace_flow, godotiq_project_summary, godotiq_file_context, godotiq_asset_registry, godotiq_suggest_scale, godotiq_animation_info, godotiq_animation_audit, godotiq_scene_tree, godotiq_ui_map, godotiq_state_inspect, godotiq_nav_query, godotiq_perf_snapshot

Validation rules

• Must be one of the three string literals. Any other value falls back to "normal".
• Per-call detail arguments always take precedence over this setting.

Example

.godotiq.json

{
  "detail_level": "brief"
}

---

addon_port

Type: number · Default: 6007

WebSocket port for the Godot addon bridge connection. Only relevant if using the addon. 18 of the 22 free bridge tools require the addon.

Validation rules

• Must be an integer between 1024 and 65535.
• Values outside this range fall back to the default (6007).
• The same port must be configured in both .godotiq.json and the addon’s settings in Godot.

Example

.godotiq.json

{
  "addon_port": 7000
}

Caution

If you change the port, update it in both places: .godotiq.json (MCP server side) and the addon’s port setting in Godot (editor side). A mismatch will prevent the bridge from connecting.

---

File Location

GodotIQ searches for .godotiq.json in the directory set via GODOTIQ_PROJECT_ROOT:

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

Or set it in your MCP client configuration’s env block:

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

The file must be in the project root, next to project.godot. Subdirectory configurations are not supported. See Configuration for details on GODOTIQ_PROJECT_ROOT.

Hot Reload

Configuration changes take effect on the next tool call. No restart of the MCP server required.