Windsurf

Windsurf supports MCP servers through its global configuration. GodotIQ integrates with Windsurf’s Cascade AI to provide spatial, code, and runtime understanding of your Godot project.

Setup

1. Install GodotIQ:

   pip install godotiq

2. Add to Windsurf MCP config:

   Edit ~/.codeium/windsurf/mcp_config.json:

   mcp_config.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 Windsurf to activate the MCP server.

4. Verify: Ask Cascade: “Ping GodotIQ” — it should confirm the connection.

Note

Windsurf uses a global MCP config, not per-project. If you switch between Godot projects, update the --project path accordingly, or use a wrapper script that detects the current project.

Tips for Windsurf

Cascade Flows

Windsurf’s Cascade (Cmd+L / Ctrl+L) can chain GodotIQ tool calls naturally. Start with broad context, then narrow down:

“Use project_summary to understand this project, then analyze the signal flow for player damage.”

Write Mode

Use Windsurf’s Write mode for applying GodotIQ-informed changes. After the AI analyzes your code with tools like dependency_graph or signal_map, switch to Write mode to let it make the changes.

Terminal Integration

Windsurf can run terminal commands alongside MCP tool calls. This is useful for running your Godot project or checking build output while using GodotIQ’s analysis tools.

Advanced Configuration

Custom Python Environment

mcp_config.json

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

Multiple Projects

For multiple Godot projects, you can define separate MCP entries:

mcp_config.json

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

Troubleshooting

MCP server not detected

• Verify the config file path: ~/.codeium/windsurf/mcp_config.json
• Check JSON syntax — a trailing comma or missing bracket will silently fail
• Restart Windsurf completely

Permission issues

On macOS, ensure godotiq is accessible from the Windsurf process. If installed in a virtual environment, use the full path to the executable.

Installation Full installation guide with all client options.

Workflows Common workflow patterns for AI-assisted game development.