Usage

Basic Usage

Once configured, you can simply ask Claude to perform computer tasks:

• "Open Chrome and go to github.com"
• "Create a folder called 'Projects' on my desktop"
• "Find all PDFs in my Downloads folder"
• "Take a screenshot and highlight the error message"

Claude will automatically use your CUA agent to perform these tasks.

Advanced Features

Progress Reporting

The MCP server provides real-time progress updates during task execution:

• Task progress is reported as percentages (0-100%)
• Multi-task operations show progress for each individual task
• Progress updates are streamed to the MCP client for real-time feedback

Error Handling

Robust error handling ensures reliable operation:

• Failed tasks return error messages with screenshots when possible
• Session state is preserved even when individual tasks fail
• Automatic cleanup prevents resource leaks
• Detailed error logging for troubleshooting

Concurrent Task Execution

For improved performance, multiple tasks can run concurrently:

• Set concurrent=true in run_multi_cua_tasks for parallel execution
• Each task runs in its own context with isolated state
• Progress tracking works for both sequential and concurrent modes
• Resource pooling ensures efficient computer instance usage

Session Management

Multi-client support with automatic resource management:

• Each client gets isolated sessions with separate computer instances
• Sessions automatically clean up after 10 minutes of inactivity
• Resource pooling prevents resource exhaustion
• Session statistics available for monitoring

Target Computer Options

By default, the MCP server runs CUA in a virtual machine for safety. However, you can also configure it to run on your local system.

Default: Using a VM (Recommended)

The MCP server will automatically start and connect to a VM based on your platform. This is the safest option as AI actions are isolated from your host system.

No additional configuration is needed - this is the default behavior.

Option: Targeting Your Local Desktop

To have the MCP server control your local desktop instead of a VM:

1. Start the Computer Server on your host:

pip install cua-computer-server
python -m computer_server

2. Configure the MCP server to use your host system:

Add the CUA_USE_HOST_COMPUTER_SERVER environment variable to your MCP client configuration:

{
  "mcpServers": {
    "cua-agent": {
      "command": "/bin/bash",
      "args": ["~/.cua/start_mcp_server.sh"],
      "env": {
        "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-5-20250929",
        "CUA_USE_HOST_COMPUTER_SERVER": "true"
      }
    }
  }
}

export CUA_USE_HOST_COMPUTER_SERVER=true

3. Restart your MCP client (e.g., Claude Desktop) to apply the changes.

Now Claude will control your local desktop directly when you ask it to perform computer tasks.

Usage Examples

Single Task Execution

"Open Safari and navigate to apple.com"
"Create a new folder on the desktop called 'My Projects'"
"Take a screenshot of the current screen"

Multi-Task Execution (Sequential)

"Run these tasks in order: 1) Open Finder, 2) Navigate to Documents folder, 3) Create a new folder called 'Work'"

Multi-Task Execution (Concurrent)

"Run these tasks simultaneously: 1) Open Chrome, 2) Open Safari, 3) Open Finder"

Session Management

"Show me the current session statistics"
"Take a screenshot using session abc123"
"Cleanup session xyz789"

Error Recovery

"Try to open a non-existent application and show me the error"
"Find all files with .tmp extension and delete them safely"

First-time Usage Notes

API Keys: Ensure you have valid API keys:

• Add your Anthropic API key in the Claude Desktop config (as shown above)
• Or set it as an environment variable in your shell profile
• Required: The MCP server needs an API key to authenticate with the model provider

Model Selection: Choose the appropriate model for your needs:

• Claude Sonnet 4: Latest model with best performance (anthropic/claude-sonnet-4-20250514)
• Computer-Use Preview: Specialized for computer tasks (openai/computer-use-preview)
• Local Models: For privacy-sensitive environments
• Ollama: For offline usage