macos-computer-use-mcp

A standalone MCP server providing native macOS computer control — mouse, keyboard, screenshots, and app management — for any MCP-compatible agent.

Demo

https://github.com/user-attachments/assets/130bee07-1f87-4291-8483-fc47ec51e493

Screenshot & Click in action — The MCP server grants app access, captures a 2560×1664 native screenshot, clicks on-screen elements, and opens URLs — all orchestrated through standard MCP tool calls from a coding agent.

Compatibility

Works with any client that supports the Model Context Protocol, including:

• Claude Code (claude mcp add)
• OpenAI Codex (~/.codex/config.toml)
• Cursor (~/.cursor/mcp.json)
• Any other MCP-compatible agent or IDE

How It Works

The server exposes macOS system control as MCP tools. Under the hood it uses macOS native modules for low-level input simulation and system APIs:

• @ant/computer-use-input — Low-level mouse and keyboard event injection
• @ant/computer-use-swift — macOS native APIs for display management, app control, and screenshots

The MCP server process communicates over stdio, so any agent can spawn it as a subprocess and call its tools via the standard JSON-RPC protocol.

Available Tools (24)

Tool	Description
request_access	Request Accessibility permission for an app
screenshot	Capture the full screen
zoom	Zoom into a screen region
left_click	Left-click at coordinates
right_click	Right-click at coordinates
middle_click	Middle-click at coordinates
double_click	Double-click at coordinates
triple_click	Triple-click at coordinates
type	Type a string of text
key	Press a key or key combination
cursor_position	Get current mouse position
mouse_move	Move the cursor to coordinates
scroll	Scroll at coordinates
drag	Drag from one point to another
left_click_drag	Left-click and drag
get_display_size	Get screen dimensions
list_displays	List all connected displays
get_frontmost_app	Get the currently active application
list_installed_apps	List all installed applications
open_app	Open an application by name or bundle ID
close_app	Close an application
focus_app	Bring an application to the foreground
get_screen_content	Get accessibility tree for screen content
wait	Wait for a specified duration

Installation

curl -fsSL https://raw.githubusercontent.com/Zooeyii/macos-computer-use-mcp/main/install.sh | bash

Or manually:

git clone https://github.com/Zooeyii/macos-computer-use-mcp.git ~/.local/share/macos-computer-use-mcp
cd ~/.local/share/macos-computer-use-mcp
npm install
npm run build

Configuration

Claude Code

claude mcp add -s user computer-use-standalone node $HOME/.local/share/macos-computer-use-mcp/dist/cli.js

Or add to ~/.claude/mcp.json:

{
  "computer-use-standalone": {
    "type": "stdio",
    "command": "node",
    "args": ["$HOME/.local/share/macos-computer-use-mcp/dist/cli.js"]
  }
}

OpenAI Codex

Add to ~/.codex/config.toml:

[mcp_servers.computer-use-standalone]
command = "node"
args = ["$HOME/.local/share/macos-computer-use-mcp/dist/cli.js"]

Or via CLI:

codex mcp add computer-use-standalone -- node $HOME/.local/share/macos-computer-use-mcp/dist/cli.js

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "computer-use-standalone": {
      "command": "node",
      "args": ["$HOME/.local/share/macos-computer-use-mcp/dist/cli.js"]
    }
  }
}

Requirements

• macOS (Darwin) — macOS-only due to native module dependencies
• Node.js 18+
• Accessibility Permission — Required for mouse/keyboard control
  • System Settings → Privacy & Security → Accessibility
• Screen Recording Permission — Required for screenshots
  • System Settings → Privacy & Security → Screen Recording

Architecture

MCP Client (Claude Code / Codex / Cursor / any agent)
      │
      │  stdio (JSON-RPC / MCP protocol)
      │
      ▼
macos-computer-use-mcp (this server)
      │
      ├── MCP Server
      │     └── Tool handler
      │
      ├── Tool Definitions
      │     ├── Input tools (click, drag, scroll, type, key)
      │     ├── Screen tools (screenshot, zoom, display info)
      │     └── App tools (open, close, focus, list)
      │
      └── Executor
            │
            ├── @ant/computer-use-input.node
            │     └── Mouse / keyboard event injection
            │
            └── @ant/computer-use-swift
                  └── macOS native APIs
                        ├── App management
                        ├── Display control
                        └── Screenshot capture

Project Structure

macos-computer-use-mcp/
├── src/
│   ├── cli.ts          # MCP server entry point
│   ├── tools.ts        # Tool definitions
│   └── executor.ts     # Platform implementations
├── install.sh          # One-line installer
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── README.md

Development

# Install dependencies
npm install

# Build
npm run build

# Run directly
node dist/cli.js

# Type-check only
npm run typecheck

Disclaimer

This project is for educational and research purposes.

Native module interfaces are based on publicly observable runtime behavior.

Use at your own risk. Only run in trusted environments — computer use grants full control of your mouse, keyboard, and screen.

License

MIT