Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/trycua/cua/llms.txt

Use this file to discover all available pages before exploring further.

Cua Driver is a generic Model Context Protocol (MCP) server. Any agent harness, IDE extension, or workflow tool that can launch a local stdio MCP process can connect to it, discover the full computer-use tool catalog, and issue actions against the desktop. This page explains the server’s configuration, tool naming conventions, introspection commands, and integration patterns for common environments.

​
How Cua Driver exposes MCP

Running cua-driver mcp starts a stdio MCP server and blocks until stdin closes. The server implements the MCP protocol version 2025-06-18 and advertises 54 tools. Process ownership depends on platform:
  • macOS — bare cua-driver mcp proxies to the installed CuaDriver.app daemon, which holds the stable Accessibility and Screen Recording identity. Pass --direct to make the MCP process itself own the runtime (useful when the spawning app already holds the required TCC grants).
  • Windows and Linux — bare cua-driver mcp owns its SDK runtime directly and shuts it down on stdin EOF. Pass --socket <endpoint> to connect to an existing daemon instead.

​
JSON MCP configuration block

Paste this block into any MCP configuration file to register Cua Driver. Replace the command value with the absolute path returned by which cua-driver or cua-driver mcp-config: 
{
  "mcpServers": {
    "cua-driver": {
      "command": "/absolute/path/to/cua-driver",
      "args": ["mcp"]
    }
  }
}
For a single-platform quick start that uses whatever is on PATH: 
{
  "mcpServers": {
    "cua-driver": {
      "command": "cua-driver",
      "args": ["mcp"]
    }
  }
}
Use absolute paths in production configurations. IDE extensions and agent runtimes often inherit a reduced PATH that does not include the directory where cua-driver is installed.

​
Tool naming convention

All 54 Cua Driver tools use snake_case names. The same name works in MCP (tools/call) and in the CLI (cua-driver <name> '<JSON-args>'):
CategoryExample tools
Sessionstart_session, end_session
Discoverylist_apps, list_windows
Inspectionget_window_state, get_accessibility_tree
Navigationlaunch_app, activate_window, move_window
Inputclick, double_click, right_click, drag, scroll, type_text, press_key, hotkey
Browserget_text, query_dom, click_element, execute_javascript
Cursormove_cursor, get_cursor_position
Configset_config, check_permissions
Recordingstart_recording, stop_recording
Tool responses are MCP CallTool.Result envelopes: a text content block prefixed with a ✅ summary (or the error reason on failure), plus optional image or structured-content blocks for tools that produce screenshots or accessibility trees.

​
Inspect available tools

List every tool the running server exposes: 
cua-driver list-tools
Inspect the full schema for a specific tool: 
cua-driver describe get_window_state
The describe output shows the tool’s description, all input parameters with their types and whether they are required, and the response shape. Use this when writing a filtered allow-list or when debugging unexpected tool behavior.

​
The --direct flag

On macOS, --direct makes the MCP process own the Cua Driver runtime instead of proxying to the daemon: 
cua-driver mcp --direct
Use --direct when the process that launches the MCP server already holds Accessibility and Screen Recording permission — for example, inside a signed Electron app that owns its TCC row. The process must not combine --direct with --socket.

​
Claude Code

Register Cua Driver in Claude Code with one command: 
claude mcp add --transport stdio cua-driver -- cua-driver mcp
For the computer-use compatibility profile: 
claude mcp add --transport stdio cua-computer-use \
  -- cua-driver mcp --claude-code-computer-use-compat
See the Claude Code integration guide for the Agent SDK, native callbacks, and local-model setup.

​
Cursor

Add Cua Driver to Cursor’s MCP configuration file (.cursor/mcp.json in your project or the global config): 
{
  "mcpServers": {
    "cua-driver": {
      "command": "/absolute/path/to/cua-driver",
      "args": ["mcp"]
    }
  }
}
Reload the MCP server list in Cursor’s settings after saving the file. Cursor will query tools/list on the next session start and make all 54 tools available in its agent panel.

​
Muse Code and other IDE integrations

Any IDE that implements the MCP client protocol and supports stdio transport can connect to Cua Driver. The configuration shape is identical across all of them: 
{
  "mcpServers": {
    "cua-driver": {
      "command": "/absolute/path/to/cua-driver",
      "args": ["mcp"],
      "required": true
    }
  }
}

​
Session management across tools

Most Cua Driver tools accept an optional session parameter. Passing a consistent session name across calls ties observations, input actions, and recordings to the same logical run: 
# Start a named session
cua-driver call start_session '{"session": "my-task-001", "capture_scope": "window"}'

# Use the session in every subsequent call
cua-driver call list_windows '{"session": "my-task-001"}'
cua-driver call get_window_state '{"pid": 1234, "window_id": 5678, "session": "my-task-001"}'

# End the session when done
cua-driver call end_session '{"session": "my-task-001"}'
When an MCP agent harness manages the session, start it before the agent loop and end it in a finally block so recordings and state are always cleaned up.

​
macOS permissions

On macOS, the process or daemon that owns the Cua Driver runtime must have Accessibility and Screen Recording permission. Verify the status: 
cua-driver doctor
Grant missing permissions: 
cua-driver permissions grant

Build docs developers (and LLMs) love

Get started for freeTalk to us