Godot Addon

The GodotIQ addon is a Godot editor plugin (pure GDScript, ~500 lines) that enables 18 free bridge tools for live editor/game interaction. It connects the running Godot editor to the MCP server over WebSocket (port 6007), enabling scene editing, screenshots, run/stop game, camera control, runtime monitoring, editor integration, input simulation, UI mapping, and navigation queries.

The addon is free, no license required. It ships with 5 GDScript files + plugin.cfg (6 files total):

• godotiq_plugin.gd
• godotiq_server.gd
• godotiq_runtime.gd
• godotiq_debugger.gd
• godotiq_logger.gd
• plugin.cfg

What the Addon Enables

Without the addon, 18 tools work from the filesystem alone (4 free: godotiq_script_ops, godotiq_file_ops, godotiq_animation_info, godotiq_ping + all 14 Pro intelligence tools). With the addon, 18 additional free bridge tools become available:

Tool	Description
godotiq_editor_context	Call FIRST alongside project_summary. Returns editor state: open scenes, selected nodes, is game running, project path
godotiq_scene_tree	Live editor scene tree showing actual state with transforms, scripts, groups, and visibility
godotiq_node_ops	Core scene editing tool. Batch operations with Ctrl+Z undo
godotiq_build_scene	Create multiple nodes in a scene using high-level patterns
godotiq_save_scene	Persist editor changes to disk
godotiq_exec	Execute GDScript code in game or editor context
godotiq_run	Start or stop the Godot game
godotiq_input	Simulate player input in the running game
godotiq_screenshot	Visual verification of the game or editor viewport
godotiq_camera	Editor 3D camera control
godotiq_state_inspect	Query runtime property values
godotiq_perf_snapshot	FPS, draw calls, memory, node count from the running game
godotiq_watch	Persistent property monitoring
godotiq_undo_history	Review undo/redo state and recent action history
godotiq_check_errors	Check GDScript files for compilation/parse errors
godotiq_verify_motion	Verify a node property changes over time
godotiq_ui_map	Map all UI elements on screen
godotiq_nav_query	Live pathfinding via NavigationServer3D

Installation

1. Install the addon using the CLI:

   godotiq install-addon <REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>

   This copies the addon into addons/godotiq/ and injects GodotIQ guidance into supported AI client convention files such as CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, and .github/copilot-instructions.md.

   Use --dry-run to preview without writing files:

   godotiq install-addon --dry-run <REPLACE_WITH_YOUR_GODOT_PROJECT_PATH>

2. Enable the plugin:

   Open your project in Godot: Project Settings → Plugins → GodotIQ → Enable

3. 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 WebSocket port (default: 6007)
• 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 WebSocket connection:

AI Agent ←(stdio)→ Python MCP Server ←(WebSocket:6007)→ GDScript Addon in Godot Editor
                                                              ↕
                                                    EngineDebugger (IPC)
                                                              ↕
                                                    Running Game (autoload)

1. Your AI client sends a tool call to the MCP server (stdio).
2. The MCP server sends a command to the addon over WebSocket.
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 6007. 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 (started by your AI client via the .mcp.json configuration).
• 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 6007. 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.x. The addon is pure GDScript with no version constraints beyond Godot 4.

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 is free and included with the MIT-licensed Community package. The 18 bridge tools it enables are free, no license required.

PRO tools (14 intelligence tools) are delivered through the private Pro bundle after license validation. Set GODOTIQ_LICENSE_KEY in your MCP client config. Pro tools are filesystem-only and do not require the addon.

Configuration Reference Full .godotiq.json schema including addon_port.

Installation Guide Set up GodotIQ and configure your MCP client.