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

macos-computer-use-mcp