Cursor

Cursor supports MCP servers through its configuration file. GodotIQ integrates with Cursor’s AI to give it spatial, code, and runtime understanding of your Godot project.

Setup

1. Install GodotIQ:

   pip install godotiq

2. Create the MCP config file:

   Create .cursor/mcp.json in your project root:

   .cursor/mcp.json

   {
     "mcpServers": {
       "godotiq": {
         "command": "godotiq",
         "args": ["--project", "/path/to/your/godot/project"]
       }
     }
   }

   Replace the path with your Godot project root. Alternatively, use uv and set GODOTIQ_PROJECT_ROOT — see Installation for details.

3. Restart Cursor to load the MCP server.

4. Verify: Ask Cursor’s AI: “Ping GodotIQ” — it should confirm the connection.

Note

If godotiq is not on your system PATH, use the full path to the executable. Find it with which godotiq (macOS/Linux) or where godotiq (Windows).

Tips for Cursor

Use Composer Mode

Cursor’s Composer mode (Cmd+I / Ctrl+I) works best for GodotIQ workflows. It lets the AI call tools, read results, and make code changes in a single flow.

Context Files

Add your .godotiq.json configuration file to Cursor’s context (drag it into the chat or use @file) so the AI understands your project’s conventions and settings.

GDScript Editing

When the AI suggests GDScript changes based on GodotIQ analysis, you can apply them directly in the editor. Common workflow:

1. Ask about a problem: “Why does the enemy get stuck at the door?”
2. GodotIQ analyzes the spatial layout and code flow
3. Cursor suggests a fix in the relevant .gd file
4. Review and apply with one click

Multi-File Operations

Cursor excels at multi-file refactoring. Use GodotIQ’s impact_check first to understand the blast radius, then let Cursor make the changes across all affected files.

Advanced Configuration

Environment Variables

If your Python environment isn’t the system default:

.cursor/mcp.json

{
  "mcpServers": {
    "godotiq": {
      "command": "/path/to/venv/bin/godotiq",
      "args": ["--project", "/path/to/your/godot/project"]
    }
  }
}

Bridge Port

For Pro addon users with a custom bridge port:

.cursor/mcp.json

{
  "mcpServers": {
    "godotiq": {
      "command": "godotiq",
      "args": [
        "--project", "/path/to/your/godot/project",
        "--bridge-port", "6551"
      ]
    }
  }
}

Troubleshooting

MCP server not loading

• Ensure .cursor/mcp.json is in the project root (same level as project.godot)
• Check that the command path is correct and godotiq is installed
• Restart Cursor completely (quit and reopen)

Tools not appearing

Cursor may need a moment to discover available tools after restart. If tools still don’t appear, check the MCP server logs in Cursor’s output panel.

Installation Full installation guide with all client options.

Workflows Common workflow patterns for AI-assisted game development.