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
Spatial	scene_map, placement, spatial_audit
Code	dependency_graph, signal_map, impact_check, validate
Flow	trace_flow
Memory	project_summary, file_context
Assets	asset_registry, suggest_scale
Animation	animation_info, animation_audit
Scene Editing	node_ops, build_scene, save_scene, script_ops
Visual	screenshot, camera
Runtime	run, state_inspect, watch, verify_motion, perf_snapshot
Editor	editor_context, scene_tree, undo_history, check_errors, exec
I/O	file_ops, input, ui_map, nav_query
Utility	ping

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": ["run", "node_ops", "input", "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 validate tool when run.

How it works

1. Define conventions as human-readable strings.
2. Run the 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 validate.
• Empty strings are ignored.
• Conventions are not enforced automatically — they are only checked when 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

scene_map, spatial_audit, dependency_graph, signal_map, impact_check, validate, trace_flow, project_summary, file_context, asset_registry, suggest_scale, animation_info, animation_audit, scene_tree, ui_map, state_inspect, nav_query, 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: 6550

TCP port for the Godot addon bridge connection. Only relevant if using the Pro addon — the 15 free tools don’t use this setting.

Validation rules

• Must be an integer between 1024 and 65535.
• Values outside this range fall back to the default (6550).
• 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 passed via --project or set in GODOTIQ_PROJECT_ROOT:

godotiq --project /path/to/godot/project

Or set the environment variable:

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.