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.

Claude Code can launch Cua Driver as a local stdio MCP server, giving Claude direct access to the 54 computer-use tools that Cua Driver exposes. This page covers the one-command registration path, the computer-use compatibility profile for Claude’s built-in computer-use tool format, and how to use the Claude Agent SDK for programmatic agent loops.

​
Register Cua Driver with Claude Code

After installing Cua Driver, register it as an MCP server with a single command: 
claude mcp add --transport stdio cua-driver -- cua-driver mcp
claude mcp list
Restart Claude Code or open a fresh session after adding the server. On macOS, the CuaDriver.app daemon that owns Accessibility and Screen Recording permission must be running before you start the session. To generate an absolute-path command that matches your installed Cua Driver version exactly, run: 
cua-driver mcp-config --client claude
This prints the recommended claude mcp add invocation with the resolved executable path, which is useful when cua-driver is not on the default shell PATH that Claude Code inherits.
On macOS, bare cua-driver mcp proxies to the installed CuaDriver.app daemon so Accessibility and Screen Recording grants retain the app-bundle identity. On Windows and Linux, the MCP process owns its runtime directly and shuts it down when stdin closes.

​
Computer-use compatibility mode

Claude Code also supports Claude’s built-in computer-use tool format. Register the compatibility profile under a separate server name: 
claude mcp add --transport stdio cua-computer-use \
  -- cua-driver mcp --claude-code-computer-use-compat
claude mcp list
With this profile active, Cua Driver keeps all of its normal MCP tools and changes only screenshot: in compatibility mode screenshot requires pid and window_id and captures that specific window only. The mcp__cua-computer-use__screenshot tool name is the image-grounding cue that Claude Code uses for its vision/computer-use-style flow.
You can have both cua-driver and cua-computer-use registered simultaneously. Use the full cua-driver catalog for complex tasks that need fine-grained control, and the compat profile for Claude workflows that already use the built-in computer-use format.

​
Claude Agent SDK integration

The Claude Agent SDK supports Cua Driver through two routes: same-process native callbacks and the external MCP boundary. The native route is best for applications that own the driver lifecycle; the MCP route is best when Claude is an external agent.

​
Prerequisites

From libs/cua-driver/examples/agent-sdks: 
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
Authenticate the Claude Agent SDK using its normal local login or the ANTHROPIC_API_KEY environment variable.

​
Native callbacks route

The native route runs the driver in the same process as your application. The SDK’s in-process MCP server adapter calls CuaDriver.create() directly — no subprocess or socket involved. 
.venv/bin/python claude_agent.py --route native \
  "Inspect the fixture, enter a short value, submit it, and verify the result"
The examples expose four tools: observe_desktop, click_desktop, type_text, and press_key. Every mutation returns a fresh desktop observation. If a call times out, the handler labels its outcome unknown and instructs the model to inspect before retrying.

​
MCP route

The MCP route runs cua-driver mcp as an external subprocess. Claude discovers the full live tool catalog at runtime. 
# Simplified from libs/cua-driver/examples/agent-sdks/claude_agent.py
import asyncio
from uuid import uuid4
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, ResultMessage

async def run_desktop_task(task: str) -> None:
    session = f"claude-mcp-{uuid4().hex[:12]}"
    # Start the Cua session before creating the Claude instance
    await driver_call("start_session", {"session": session, "capture_scope": "auto"})
    try:
        options = ClaudeAgentOptions(
            tools=[],
            mcp_servers={
                "cua_driver": {
                    "type": "stdio",
                    "command": "cua-driver",
                    "args": ["mcp"],
                }
            },
            strict_mcp_config=True,
            allowed_tools=["mcp__cua_driver"],
            permission_mode="dontAsk",
        )
        async with ClaudeSDKClient(options=options) as client:
            await client.query(task)
            async for message in client.receive_response():
                if isinstance(message, ResultMessage):
                    print(message.result)
    finally:
        await driver_call("end_session", {"session": session})

asyncio.run(run_desktop_task("Open Calculator and compute 7 × 8"))

​
Practical example: drive Calculator

Once registered, ask Claude Code to perform a desktop task using natural language: 
Use the cua-driver MCP tools to open Calculator, compute 2 + 3, and verify
the display shows 5. Take a fresh window state before every action and verify
the result afterward.
Claude will use launch_app to open Calculator, get_window_state to read the accessibility tree, click to press the digit and operator keys, and get_window_state again to verify the displayed result.
Always run trusted tasks with these agent integrations. The examples disable interactive approval prompts and intentionally exclude Claude Code’s built-in shell and file tools to prevent unintended side effects.

​
macOS permissions

On macOS, Cua Driver requires Accessibility and Screen Recording permission. Run the permissions check before starting any session: 
cua-driver doctor
If permissions are missing, follow the guided setup: 
cua-driver permissions grant

Build docs developers (and LLMs) love

Get started for freeTalk to us