Cua Mac: macOS MCP Server for AI Agents

cua-mac is a macOS Model Context Protocol (MCP) server that gives an AI agent direct access to the user's real Mac host over stdio.

It is built for computer-use workflows where an MCP client needs to click, type, inspect windows, read the accessibility tree, interact with files, and automate native macOS apps instead of a sandboxed VM or browser-only environment.

Why This MCP Server Exists

Most MCP servers expose APIs, databases, or browser automation. This one exposes the host operating system itself.

Use it when you need an AI agent to:

• control the macOS cursor and keyboard
• inspect and manipulate native app windows
• read and write files on the host machine
• access clipboard contents
• capture screenshots for perception loops
• query the focused accessibility tree for UI automation
• launch apps and open files or URLs

Key Features

• 48 MCP tools for host automation, file access, window management, accessibility inspection, and lightweight web search
• direct macOS interaction through a Swift helper plus a thin Node MCP server
• permission-aware error handling for Accessibility and Screen Recording
• structured JSON tool outputs for MCP clients that consume structuredContent
• safer destructive operations with protected-path checks for file and directory deletion
• bounded shell command execution with timeout reporting

Who Should Use It

• teams building computer-use agents on macOS
• MCP client developers who need native OS control
• researchers prototyping AI desktop automation
• developers integrating Model Context Protocol tools into agent loops

Supported Environment

• macOS
• Node.js 18+
• Swift toolchain available at /usr/bin/swiftc

This server does not support Linux or Windows.

Installation

git clone https://github.com/ashish200729/personal-ai-computer-mcp.git
cd personal-ai-computer-mcp
npm install

The Swift helper is compiled automatically on first run.

Run The MCP Server

cd /path/to/personal-ai-computer-mcp
node ./src/index.mjs

MCP Client Configuration

Use this server in any MCP-compatible client that supports stdio servers.

{
  "mcpServers": {
    "cua-mac": {
      "command": "node",
      "args": ["/absolute/path/to/personal-ai-computer-mcp/src/index.mjs"]
    }
  }
}

Tool Categories

Screenshots and Perception

• computer_screenshot
• computer_get_screen_size
• computer_get_cursor_position

Mouse and Keyboard Automation

• computer_click
• computer_double_click
• computer_move
• computer_drag
• computer_scroll
• computer_mouse_down
• computer_mouse_up
• computer_type
• computer_press_key
• computer_hotkey
• computer_key_down
• computer_key_up

Clipboard and Shell

• computer_clipboard_get
• computer_clipboard_set
• computer_run_command

Host File System

• computer_file_read
• computer_file_write
• computer_file_exists
• computer_directory_exists
• computer_list_directory
• computer_create_directory
• computer_delete_file
• computer_delete_directory
• computer_get_file_size
• computer_open

Apps and Windows

• computer_launch_app
• computer_get_active_window
• computer_get_window_name
• computer_get_window_size
• computer_get_window_position
• computer_set_window_size
• computer_set_window_position
• computer_activate_window
• computer_minimize_window
• computer_maximize_window
• computer_close_window
• computer_get_app_windows
• computer_get_desktop_environment
• computer_set_wallpaper

Accessibility and Discovery

• computer_get_accessibility_tree
• computer_find_element
• computer_web_search
• computer_permissions_status
• computer_request_permissions

Example Use Cases

macOS Computer Use

An AI agent can capture a screenshot, move the mouse, click a button, type into a native app, and verify the next state with another screenshot.

Native App Automation

A client can inspect the focused window, locate controls through the accessibility tree, and operate Finder, System Settings, browsers, editors, or internal desktop tools.

Host File Operations

An agent can read logs, create directories, write files, inspect file sizes, and open local artifacts with the default macOS handler.

Tool Discovery Workflow

An agent can use computer_web_search for quick discovery, then open the selected URL in the user's default browser with computer_open.

Production Notes

• UI coordinate tools use absolute macOS screen coordinates.
• computer_screenshot requires Screen Recording permission.
• cursor, keyboard, and accessibility tools require Accessibility permission.
• computer_run_command is a fallback. Prefer dedicated tools when they exist.
• computer_run_command supports timeout_ms and returns timed_out.
• computer_find_element requires at least one of role, title, or value.
• file and directory deletion reject a small set of protected paths such as /, /System, /Users, the current working directory, and the current home directory
• window ids are emitted as pid:index

Troubleshooting

Accessibility Actions Fail

Call computer_permissions_status first. If Accessibility access is missing, call computer_request_permissions and approve the MCP client or terminal in:

System Settings > Privacy & Security > Accessibility

Screenshots Fail

Grant Screen Recording permission to the MCP client or terminal in:

System Settings > Privacy & Security > Screen Recording

Screen Size Returns An Error

That means the current macOS session is not exposing valid display dimensions to the helper process. In practice this usually points to a headless, locked, or otherwise restricted session.

Repository Metadata Recommendations

To improve GitHub discovery and click-through rate further, configure these repository settings in GitHub:

• description: macOS MCP server for AI agents, computer use, native app automation, screenshots, accessibility, and host OS control
• website: https://github.com/trycua/cua/tree/main/mcp
• topics: mcp, model-context-protocol, macos, ai-agents, computer-use, desktop-automation, accessibility, host-automation, tool-use, agent-tools
• social preview image: a 1280x640 image showing macOS automation plus the phrases macOS MCP Server and AI Agent Computer Use
• if trycua/cua is intended to be open source, add a repository-level LICENSE file at the repo root so GitHub can classify it as open source

Search Intent This README Covers

This README is intentionally optimized for queries such as:

• macOS MCP server
• Model Context Protocol macOS
• AI agent computer use macOS
• desktop automation MCP
• native app automation for AI agents
• host OS control for MCP clients
• macOS accessibility automation server

Related Project Links

• repository root: https://github.com/trycua/cua
• package path: https://github.com/trycua/cua/tree/main/mcp