computer-use-mac-mcp

computer-use-mac-mcp

中文文档 | English

MCP server for macOS desktop automation — screenshot, click, type, scroll and more.

Gives Claude (or any MCP-compatible agent) the ability to see and control your Mac. Implements the standard mcp__computer-use__* tool interface so it works with Claude Desktop, Claude Code, Cursor, and any other MCP client — no API key required at the tool level.

Pure JS, no native addons. Uses screencapture, osascript (JXA/AppKit), and CoreGraphics CGEvent.

Highlights

• Standard MCP interface — plug into any MCP-compatible client, not locked to a specific AI provider
• Retina display aware — correctly scales screenshot-space coordinates to physical pixels
• CJK / Unicode text input — automatically routes non-ASCII text through clipboard paste (fixes garbled Chinese/Japanese/Korean input)
• Multi-monitor support — switch_display tool lets agents target any connected display
• No native compilation — pure JS implementation, works with Node.js ≥ 18 or Bun ≥ 1.3

Requirements

• macOS
• Node.js ≥ 18 or Bun ≥ 1.3
• Screen Recording permission — System Settings → Privacy & Security → Screen Recording
• Accessibility permission — System Settings → Privacy & Security → Accessibility

Quick Start

# 1. Clone
git clone https://github.com/somethingforheheda/computer-use-mac-mcp.git
cd computer-use-mac-mcp

# 2. Install dependencies
npm install

# 3. Add to your MCP client config (see below)

Claude Code CLI

computer-use is a reserved name in Claude Code CLI. Use a different name:

claude mcp add -s user mac-control /path/to/node /path/to/computer-use-mac-mcp/index.js

Tools will be available as mcp__mac-control__screenshot, mcp__mac-control__left_click, etc.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "computer-use": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/computer-use-mac-mcp/index.js"]
    }
  }
}

Claude Code / jarvis-cc

{
  "computer-use": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/computer-use-mac-mcp/index.js"]
  }
}

Available Tools (15)

| Tool | Description | |------|-------------| | screenshot | Capture the screen as JPEG | | left_click | Left-click at (x, y) | | right_click | Right-click at (x, y) | | middle_click | Middle-click at (x, y) | | double_click | Double-click at (x, y) | | left_click_drag | Click and drag from one point to another | | mouse_move | Move cursor without clicking | | scroll | Scroll at (x, y) | | cursor_position | Get current cursor coordinates | | type | Type text — auto clipboard for CJK/Unicode | | key | Press a key or combo (e.g. command+c, command+a) | | hold_key | Hold a key for a specified duration | | zoom | Capture and zoom a screen region | | request_access | Declare which apps the agent will control | | switch_display | Switch active display for multi-monitor setups |

Coordinate System

Coordinates are in screenshot-space pixels. Always call screenshot first — the server caches the display dimensions and uses them to correctly map click coordinates to physical pixels (including Retina 2× scaling).

Multi-monitor

# Switch to external display (0 = primary, 1 = secondary, ...)
switch_display { "display": 1 }

After switching, subsequent screenshot and click tools target the selected display.

How it works

Three packages under packages/:

| Package | Responsibility | Implementation | |---------|---------------|----------------| | computer-use-mcp | MCP server, tool definitions, coordinate dispatch | MCP SDK + bindSessionContext | | computer-use-swift | Screenshot, app listing, app activation | screencapture + osascript (JXA/AppKit) | | computer-use-input | Mouse movement, clicks, scroll, keyboard | JXA + CoreGraphics CGEventCreateMouseEvent / CGEventCreateKeyboardEvent |

The entry point (index.js) wires these together and exposes them over stdio as an MCP server. No subprocess is spawned per tool call — everything runs in a single Node process.

Comparison

| | this project | PallavAg/claude-computer-use-macos | |---|---|---| | Language | JS (Node/Bun) | Python | | Interface | MCP Server (any client) | Standalone script (Claude API only) | | Retina support | ✅ | ❌ | | CJK text input | ✅ auto clipboard | ❌ garbled output | | Multi-monitor | ✅ switch_display | ❌ | | Needs API key to run | ❌ | ✅ | | Native addons | ❌ pure JS | ❌ pure Python |

License

MIT