Godot Addon

The GodotIQ addon is a Godot editor plugin that unlocks 20 Pro tools across 5 categories: Scene Editing, Visual, Runtime, Editor, and I/O. It connects the running Godot editor to the MCP server over TCP, enabling real-time interaction: scene editing, screenshots, run/stop game, camera control, runtime monitoring, editor integration, filesystem operations, input simulation, UI mapping, and navigation queries.

The addon requires a Pro license.

What the Addon Unlocks

Without the addon, GodotIQ provides 15 free tools that work by reading project files directly. With the addon, 20 Pro tools become available:

Category	Tool	Description
Scene Editing	node_ops	Batch scene editing with Ctrl+Z undo: move, rotate, scale, set_property, add_child, delete, duplicate, reparent
Scene Editing	build_scene	Create multiple nodes using high-level patterns. One call = many nodes with undo
Scene Editing	save_scene	Persist editor changes to disk
Scene Editing	script_ops	Read, write, or patch GDScript files with convention validation
Visual	screenshot	Visual verification of game or editor viewport
Visual	camera	Editor 3D camera control: get position, reposition, focus on node
Runtime	run	Start or stop the Godot game from the editor
Runtime	state_inspect	Query runtime property values. CHEAPER than screenshots — use first
Runtime	watch	Persistent property monitoring across game interactions
Runtime	verify_motion	Verify node property changes over time (proves movement/animation)
Runtime	perf_snapshot	FPS, draw calls, memory, node count from running game
Editor	editor_context	Editor state: open scenes, selected nodes, is game running, project path
Editor	scene_tree	Live editor scene tree with transforms, scripts, groups, visibility
Editor	undo_history	Review what was changed — undo/redo state and action history
Editor	check_errors	Check GDScript files for compilation/parse errors
Editor	exec	Execute GDScript code. Last resort — prefer dedicated tools
I/O	file_ops	Filesystem operations within Godot project: list, read, write, move, delete, search, tree, rename
I/O	input	Simulate player input: actions, keys, UI taps, waits
I/O	ui_map	Map all UI elements: positions, text, interactivity, visibility
I/O	nav_query	Live pathfinding via NavigationServer3D. Can A reach B?

Installation

1. Download the addon from your purchase confirmation email or the GodotIQ dashboard.

2. Copy to your project:

   Extract the archive and copy the addons/godotiq/ folder into your Godot project’s addons/ directory:

   your_project/
   ├── addons/
   │   └── godotiq/
   │       ├── plugin.cfg
   │       ├── godotiq_bridge.gd
   │       └── ...
   ├── project.godot
   └── .godotiq.json

3. Enable the plugin:

   Open your project in Godot, go to Project → Project Settings → Plugins, and enable GodotIQ.

4. Verify the connection:

   A “GodotIQ” panel appears at the bottom of the editor. The status indicator shows:

   • Green — Connected to the MCP server
   • Yellow — Waiting for connection
   • Red — Connection error

   Ask your AI: “Take a screenshot” — if it works, the addon is connected.

Tip

The addon auto-connects when the MCP server starts. You don’t need to start them in any particular order.

Bottom Panel UI

When enabled, the addon adds a panel to the bottom dock of the Godot editor:

• Status indicator — Connection state (green/yellow/red)
• Port display — Current TCP port (default: 6550)
• Log viewer — Recent bridge commands and responses
• Reconnect button — Manually retry the connection if it drops

The panel is informational — all interaction happens through your AI client. The panel helps you verify the connection is active and debug issues.

Bridge Architecture

The addon communicates with the MCP server over a local TCP connection:

AI Client → MCP Server (Python) → TCP:6550 → Godot Addon (GDScript)

1. Your AI client sends a tool call to the MCP server.
2. The MCP server sends a command to the addon over TCP.
3. The addon executes the command in the Godot editor via EngineDebugger.
4. The result is sent back through the same path.

All communication is local (localhost only). No data leaves your machine.

Port Configuration

The default port is 6550. To change it:

1. Set addon_port in .godotiq.json:

   .godotiq.json

   {
     "addon_port": 7000
   }

2. In Godot, go to Project → Project Settings → GodotIQ → Port and set the same value.

Caution

Both sides must use the same port. A mismatch results in a “Connection refused” error.

GDScript API

For advanced users, the addon exposes a GDScript API for custom integrations:

# Access the bridge singleton
var bridge = GodotIQBridge.instance

# Check connection status
if bridge.is_connected():
    print("GodotIQ bridge is active on port ", bridge.port)

# Send a custom response (for plugin developers)
bridge.send_response(request_id, {"status": "ok", "data": result})

The GDScript API is primarily for addon developers extending GodotIQ’s functionality. Most users interact entirely through their AI client.

Troubleshooting

Addon not appearing in Plugins list

• Verify the folder structure: addons/godotiq/plugin.cfg must exist.
• Check that plugin.cfg has the correct [plugin] section.
• Restart the Godot editor after copying the addon files.

Connection status is Yellow (waiting)

• Ensure the MCP server is running (godotiq --project /path/to/project).
• The addon auto-retries every 5 seconds — wait a moment after starting the server.
• Check that the port matches in both .godotiq.json and the Godot addon settings.

Connection status is Red (error)

• Port conflict: Another process may be using port 6550. Change the port in both .godotiq.json and the addon settings.
• Firewall: Ensure localhost connections on the configured port are not blocked.
• Godot version: The addon requires Godot 4.2 or later. Earlier versions lack the required EngineDebugger API.

Bridge tools return errors but free tools work

• The MCP server is running but the addon isn’t connected. Check the bottom panel status.
• If the status is green but tools fail, check the log viewer for error details.

”Connection refused” error

• Port mismatch between .godotiq.json and the addon. Verify both use the same port.
• The addon is not enabled in Project Settings → Plugins.

Licensing

The addon requires a Pro license. Pricing:

• One-time purchase — no subscription
• Lifetime updates — all future versions included
• Per-developer license — one license per person
• Commercial use — allowed under the personal license

The 15 free Community tools work without any license or addon.

Configuration Reference Full .godotiq.json schema including addon_port.

Installation Guide Set up GodotIQ and configure your MCP client.