Installation

Install the package from PyPI:

pip install cua-mcp-server

This will install:

• The MCP server
• CUA agent and computer dependencies
• An executable cua-mcp-server script in your PATH

Easy Setup Script

If you want to simplify installation, you can use this one-liner to download and run the installation script:

curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/python/mcp-server/scripts/install_mcp_server.sh | bash

This script will:

• Create the ~/.cua directory if it doesn't exist
• Generate a startup script at ~/.cua/start_mcp_server.sh
• Make the script executable
• The startup script automatically manages Python virtual environments and installs/updates the cua-mcp-server package

You can then use the script in your MCP configuration like this:

{
  "mcpServers": {
    "cua-agent": {
      "command": "/bin/bash",
      "args": ["~/.cua/start_mcp_server.sh"],
      "env": {
        "CUA_MODEL_NAME": "anthropic/claude-sonnet-4-20250514",
        "ANTHROPIC_API_KEY": "your-anthropic-api-key-here"
      }
    }
  }
}

Important: You must include your Anthropic API key for the MCP server to work properly.

Development Setup

If you're working with the CUA source code directly (like in the CUA repository), you can use the development script instead:

{
  "mcpServers": {
    "cua-agent": {
      "command": "/usr/bin/env",
      "args": [
        "bash",
        "-lc",
        "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
      ]
    }
  }
}

For host computer control (development setup):

1. Install Computer Server Dependencies:

   python3 -m pip install uvicorn fastapi
   python3 -m pip install -e libs/python/computer-server --break-system-packages

2. Start the Computer Server:

   cd /path/to/cua
   python -m computer_server --log-level debug

   This will start the computer server on http://localhost:8000 that controls your actual desktop.

3. Configure Claude Desktop:

   {
     "mcpServers": {
       "cua-agent": {
         "command": "/usr/bin/env",
         "args": [
           "bash",
           "-lc",
           "export CUA_MODEL_NAME='anthropic/claude-sonnet-4-20250514'; export ANTHROPIC_API_KEY='your-anthropic-api-key-here'; export CUA_USE_HOST_COMPUTER_SERVER='true'; export CUA_MAX_IMAGES='1'; /path/to/cua/libs/python/mcp-server/scripts/start_mcp_server.sh"
         ]
       }
     }
   }

Note: Replace /path/to/cua with the absolute path to your CUA repository directory.

⚠️ Important: When using host computer control (CUA_USE_HOST_COMPUTER_SERVER='true'), the AI will have direct access to your desktop and can perform actions like opening applications, clicking, typing, and taking screenshots. Make sure you're comfortable with this level of access.

Troubleshooting

Common Issues:

1. "Claude's response was interrupted" - This usually means:

   • Missing API key: Add ANTHROPIC_API_KEY to your environment variables
   • Invalid model name: Use a valid model like anthropic/claude-sonnet-4-20250514
   • Check logs for specific error messages

2. "Missing Anthropic API Key" - Add your API key to the configuration:

   "env": {
     "ANTHROPIC_API_KEY": "your-api-key-here"
   }

3. "model not found" - Use a valid model name:

   • ✅ anthropic/claude-sonnet-4-20250514

4. Script not found - If you get a /bin/bash: ~/cua/libs/python/mcp-server/scripts/start_mcp_server.sh: No such file or directory error, try changing the path to the script to be absolute instead of relative.

5. Host Computer Control Issues - If using CUA_USE_HOST_COMPUTER_SERVER='true':

   • Computer Server not running: Make sure you've started the computer server with python -m computer_server --log-level debug
   • Port 8000 in use: Check if another process is using port 8000 with lsof -i :8000
   • Missing dependencies: Install uvicorn and fastapi with python3 -m pip install uvicorn fastapi
   • Image size errors: Use CUA_MAX_IMAGES='1' to reduce image context size

Viewing Logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log