mac-use

A macOS MCP clone of Codex @Computer Use, built to make the same tool interfaces and desktop-control capabilities available to other coding agents.

This project reproduces the Codex Computer Use tool surface with a Node MCP server and a native Swift helper so any MCP client that supports local stdio servers can use a similar interface on macOS.

Requirements

• macOS
• Node.js 20+ recommended
• Xcode Command Line Tools with swift
• a host app with:
  • Accessibility permission
  • Screen Recording permission

For most source installs, the host app is whichever app launches the MCP server, for example:

• Terminal
• iTerm
• Warp
• Codex
• Cursor

Install

From npm:

npm install -g mac-use

From the repo root for development:

npm install
npm run build
npm run check
npm test

Permissions Setup

Grant permissions to the app that will launch the MCP server.

Examples:

• if you run it from Terminal, enable Terminal
• if you run it from Codex, enable Codex
• if you run it from Cursor, enable Cursor

macOS settings to enable:

1. System Settings > Privacy & Security > Accessibility
2. System Settings > Privacy & Security > Screen Recording or Screen & System Audio Recording

After changing permissions, fully restart the host app.

Run

Recommended source-development path:

npm run start

Installed package path:

mac-use

Alternative CLI backend:

npm run start:cli

The native-helper backend is the default path. The CLI backend exists mainly for comparison and fallback.

Smoke test:

npm run smoke

Optional app override:

npm run smoke -- TextEdit

MCP Client Config

Use the packaged launcher:

{
  "mcpServers": {
    "computer-use": {
      "command": "mac-use"
    }
  }
}

If you are running from a local checkout instead of a global install:

{
  "mcpServers": {
    "computer-use": {
      "command": "node",
      "args": ["/absolute/path/to/mac-computer-use/bin/mac-use.js"]
    }
  }
}

What It Does

The server exposes the same high-level tool set we observed from Codex Computer Use:

• list_apps
• get_app_state
• click
• drag
• type_text
• press_key
• set_value
• scroll
• perform_secondary_action

Under the hood:

• the MCP server is a Node stdio process
• the native behavior lives in helper/ComputerUseNativeHelper.swift
• the Swift helper is compiled into ~/Library/Caches/mac-use at runtime, or into MAC_USE_CACHE_DIR when that environment variable is set
• the helper handles accessibility inspection/actions, pointer/keyboard events, screenshots, and the visible second cursor overlay

Tool Summary

list_apps

Returns a user-facing inventory of running apps plus recent non-running apps when metadata is available.

Structured result includes:

• name
• bundleId
• pid
• running
• frontmost
• visible
• lastUsed
• uses

get_app_state

Returns:

• app identity
• window title
• accessibility tree text
• structured elements
• screenshot artifact when available

Structured elements include fields such as:

• index
• id
• role
• title
• description
• value
• focused
• settable
• actions
• bounds

click

Currently implemented with coordinate clicks on the native backend.

drag

Native pointer drag between coordinates.

type_text

Literal text input using native event synthesis.

press_key

Native key press support for:

• printable keys
• common special keys
• modifier combinations such as cmd+c, shift+tab

set_value

Direct AX value mutation for settable UI elements.

This is one of the strongest background-safe paths.

scroll

Native scroll at the target app/window center.

perform_secondary_action

Executes AX actions such as:

• Press
• Raise
• `S

... View full README on GitHub