Godot MCP for Windsurf: Setup & Config

What you can do with Godot in Windsurf

Pick it for Godot execution feedback and scene operations within the same MCP workflow.

• Create scenes and add configured nodes.
• Maintain project resource UID references on Godot 4.4 or newer.

Before you start: Godot in Windsurf

• Godot Engine installed locally
• Node.js 18.0.0 or newer and npm
• An MCP-compatible agent
• Godot 4.4 or newer for UID operations

GODOT_PATH overrides automatic executable detection and can be omitted when discovery works. DEBUG=true enables detailed server logging. Ensure project paths contain project.godot.

Godot Windsurf configuration

1. Choose Windsurf configuration scope

   For Godot MCP, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Godot MCP to Windsurf

   Use the godot-mcp entry below in mcpServers. Keep Godot MCP's documented stdio connection fields and your other Windsurf entries.

3. Check Godot MCP in Windsurf

   Godot MCP: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "godot-mcp": {
      "command": "npx",
      "args": [
        "@coding-solo/godot-mcp"
      ],
      "env": {
        "GODOT_PATH": "<Path to the Godot executable; optional discovery override>"
      }
    }
  }
}

Godot tools available to Windsurf

Godot's stored tool list documents 14 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

launch_editor

After refreshing Godot in Windsurf settings, check Cascade's tool list for launch_editor.

run_project

After refreshing Godot in Windsurf settings, check Cascade's tool list for run_project.

get_debug_output

After refreshing Godot in Windsurf settings, check Cascade's tool list for get_debug_output.

stop_project

After refreshing Godot in Windsurf settings, check Cascade's tool list for stop_project.

get_godot_version

After refreshing Godot in Windsurf settings, check Cascade's tool list for get_godot_version.

Report the installed engine version.

list_projects

After refreshing Godot in Windsurf settings, check Cascade's tool list for list_projects.

Discover Godot projects beneath a directory.

get_project_info

After refreshing Godot in Windsurf settings, check Cascade's tool list for get_project_info.

Inspect a project’s metadata.

create_scene

After refreshing Godot in Windsurf settings, check Cascade's tool list for create_scene.

add_node

After refreshing Godot in Windsurf settings, check Cascade's tool list for add_node.

load_sprite

After refreshing Godot in Windsurf settings, check Cascade's tool list for load_sprite.

export_mesh_library

After refreshing Godot in Windsurf settings, check Cascade's tool list for export_mesh_library.

Export scene content as a MeshLibrary resource.

save_scene

After refreshing Godot in Windsurf settings, check Cascade's tool list for save_scene.

Persist scene changes to a file.

get_uid

After refreshing Godot in Windsurf settings, check Cascade's tool list for get_uid.

Read a file’s resource UID on Godot 4.4 or newer.

update_project_uids

After refreshing Godot in Windsurf settings, check Cascade's tool list for update_project_uids.

Resave resources to refresh project UID references on Godot 4.4 or newer.

Godot: full stored tool descriptions

Troubleshooting Godot in Windsurf

• Check npx @coding-solo/godot-mcp (Node.js/npm) on the machine running Windsurf's MCP integration for Godot MCP; refresh MCP and inspect Cascade's tools.
• Check GODOT_PATH for Godot MCP; do not bypass a Windsurf permission error with a broad administrator token.
• Godot MCP uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires an installed Godot engine and Node.js 18 or newer.
• Known limitation: UID operations require Godot 4.4 or newer.
• Known limitation: Project paths must point to directories containing project.godot.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions