How to add Cua Driver to Windsurf

Background computer-use MCP server that drives native macOS, Windows, and Linux desktop apps without stealing focus. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 19k★ · stdio · no auth

Windsurf config for Cua Driver

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh)"

{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": [
        "mcp"
      ]
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Cua Driver config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Cua Driver's tools become available to Cascade.

Before you start

macOS 14 (Sonoma) or newer for the macOS backend (Windows and pre-release Linux backends also supported)
cua-driver CLI + CuaDriver.app installed via the install.sh / install.ps1 one-liner
macOS: Accessibility and Screen Recording permissions granted to CuaDriver.app (verify with `cua-driver check_permissions`)
An MCP client such as Claude Code, Cursor, Codex, or a custom client

What Cua Driver can do in Windsurf

get_window_state

Snapshot a window's accessibility tree (Screen-of-Marks markdown with each actionable element tagged [N]) plus an optional screenshot; required before acting by element_index.

get_desktop_state

Capture the overall desktop / multi-window state.

list_apps

App-level discovery: list installed / running applications.

list_windows

List the windows for a given pid.

launch_app

Launch (or focus) an app by bundle id; idempotent and returns the pid plus a windows array.

kill_app

Terminate a running application by pid.

bring_to_front

Bring an app/window to the foreground when foreground interaction is needed.

click

Click a target by element_index (AX/UIA) or by pixel x/y within a window, without raising it.

Security

Runs locally and drives the user's real desktop. On macOS it ships as an .app bundle (com.trycua.driver) and requires Accessibility and Screen Recording TCC grants in System Settings -> Privacy & Security; verify with `cua-driver check_permissions`. Requires macOS 14 (Sonoma) or newer. It can control any granted application, so only run it on machines where you trust the connected agent. No API key or remote auth is used.

Cua Driver + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Cua Driver config there under the "mcpServers" key and restart the client.

Is Cua Driver safe to use with Windsurf?

How do I add it to Claude Code?

Install the driver with the install.sh one-liner, then run `claude mcp add --transport stdio cua-driver -- cua-driver mcp`. For Claude Code's vision/computer-use grounding, register the compat server instead: `claude mcp add --transport stdio cua-computer-use -- cua-driver mcp --claude-code-computer-use-compat`.

Which platforms are supported?

macOS and Windows are supported with the same CLI/MCP server; Linux is available as a pre-release backend while platform testing continues. The macOS backend requires macOS 14 (Sonoma) or newer.

What permissions does it need?

On macOS, CuaDriver.app needs Accessibility and Screen Recording grants in System Settings -> Privacy & Security. Verify both are true with `cua-driver check_permissions`. No API key is required.

View repo Full Cua Driver page