macOS-MCP

🍎 macOS-MCP

Overview

macOS-MCP is a lightweight, open-source Model Context Protocol server that bridges AI agents and the macOS operating system. It enables seamless automation of macOS through LLMs via tasks such as file navigation, application control, UI interaction, browser automation, and system operations.

Supported Operating Systems

• macOS 12 (Monterey)
• macOS 13 (Ventura)
• macOS 14 (Sonoma)
• macOS 15 (Sequoia)
• macOS 26 (Tahoe)

Key Features

• Works with Any LLM (Vision Optional) Unlike traditional automation tools, macOS-MCP doesn't require computer vision, fine-tuned models, or specialized setup. Works seamlessly with any LLM—Claude, GPT, Gemini, or others.

• Native macOS Integration Interacts natively with macOS UI elements using the Accessibility API. Opens apps, controls windows, simulates user input, and captures desktop state without workarounds.

• Rich Toolset for Automation Complete toolkit for keyboard/mouse operations, window management, UI state capture, interactive element extraction from the accessibility tree, and AppleScript execution.

• Lightweight and Open-Source Minimal dependencies with full source code available under MIT license. Easy setup and deployment.

• Smart Context Awareness Automatically detects application state (Launchpad, Control Center, Spotlight). Scans menu bar, dock, desktop, and system UI elements intelligently.

• Customizable and Extensible Easily extend with custom tools or modify behavior to suit your specific automation needs.

Installation

Prerequisites

• Python: 3.11 or later
• UV Package Manager: Install with pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
• macOS: 12 (Monterey) or later
• Accessibility Permissions: Required for UI element interaction

Quick Start

Run the server directly:

uvx macos-mcp serve

Or with SSE/Streamable HTTP for network access

uvx macos-mcp serve --transport sse --host localhost --port 8000 uvx macos-mcp serve --transport streamable-http --host localhost --port 8000

Run it as a background service that starts now and at every login:

macos-mcp install

Or choose the HTTP transport and bind address explicitly

macos-mcp install --transport sse --host 127.0.0.1 --port 8000

This installs a launchd Launch Agent at ~/Library/LaunchAgents/com.macos-mcp.server.plist. Use macos-mcp uninstall to remove it. Logs are written to ~/.macos-mcp/server.log and ~/.macos-mcp/server.error.log.

Transport Options

Grant Required Permissions

macOS-MCP requires Accessibility and Screen Recording permissions to function properly.

Accessibility Permissions

1. Open System Settings → Privacy & Security → Accessibility
2. Click the lock icon and authenticate
3. Add the following applications:

• Your terminal application (Terminal, iTerm2, VS Code, etc.)
• Python (typically /usr/bin/python3 or the Python version managed by UV)
• UV (~/.local/bin/uv if installed locally, or the Python environment UV manages)

1. Restart the terminal after granting permissions

For `uvx` users: Grant permissions to your terminal application and Python, as uvx runs Python packages from UV's cache.

If the interpreter binary is greyed out / unselectable in the "+" picker (a known issue with UV-managed Python symlinks, e.g. .venv/bin/python3.12 → ~/.local/share/uv/python/...): don't try to add it manually. Instead, just start the server — since v0.3.10 it calls AXIsProcessTrustedWithOptions with the prompt option on startup, which asks macOS to show its native consent dialog and auto-register the running process for you. Approve that dialog and restart the server.

If you're launched as a subprocess by a parent that already holds Accessibility access (e.g. certain Claude Desktop configurations), and permission checks still fail spuriously, set MACOS_MCP_SKIP_PERMISSION_CHECK=1 to downgrade the check to a warning instead of exiting.

Screen Recording Permissions

The Snapshot tool requires Screen Recording permissions to capture screenshots:

1. Open System Settings → Privacy & Security → Screen Recording
2. Click the lock icon and authenticate
3. Add the same applications as above (terminal, Python, UV)
4. Restart the terminal after granting permissions

Note: If the Snapshot tool fails, verify both permissions are granted in System Settings.

Integration Options

Claude Desktop

1. Install Claude Desktop

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

  {

"mcpServers": { "macos-mcp": { "command": "uvx", "args": ["macos-mcp", "serve"] } } }

1. Restart Claude Desktop

Claude Desktop (connecting to an HTTP server)

Claude Desktop's claude_desktop_config.json only supports stdio-based server entries. To connect to a running macOS-MCP HTTP server (e.g. one started with macos-mcp install --transport streamable-http), use mcp-remote as a stdio-to-HTTP bridge.

This is especially useful when running multiple Claude Desktop instances (e.g. via Parall) — a single persistent HTTP server handles all of them, avoiding the overhead of spawning a separate macos-mcp process per session.

1. Start the HTTP server (one-time setup):

  macos-mcp install --transport streamable-http --host 127.0.0.1 --port 8000

2. Configure Claude Desktop to connect via mcp-remote:

  {

"mcpServers": { "macos-mcp": { "command": "npx", "args": [ "-y", "mcp-remote", "http://127.0.0.1:8000/mcp", "--transport", "http-only" ] } } }

3. Restart Claude Desktop.

If you have multiple Claude Desktop instances (e.g. Parall clones), add the same mcpServers entry to each instance's claude_desktop_config.json. All instances will share the single background server.

A migration script is included for bulk reconfiguration — see scripts/stdio-to-http-reconfig.sh.

With authentication (recommended when binding to 0.0.0.0):

  # Start server with an auth key

macos-mcp install --transport streamable-http --host 0.0.0.0 --port 8000 \ --auth-key "your-secret-token"

  {

"mcpServers": { "macos-mcp": { "command": "npx", "args": [ "-y", "mcp-remote", "http://127.0.0.1:8000/mcp", "--transport", "http-only", "--header", "Authorization: Bearer your-secret-token" ] } } }

Gemini CLI

1. Install Gemini CLI:

  npm install -g @google/gemini-cli

1. Navigate to ~/.gemini and open settings.json

1. Add the server config:

  {

"theme": "Default", "mcpServers": { "macos-mcp": { "command": "uvx", "args": ["macos-mcp", "serve"] } } }

1. Restart Gemini CLI

Claude Code

1. Install Claude Code

1. Add to your project configuration or use the MCP marketplace integration

Pi Agent

Pi does not ship with built-in MCP support, but macOS-MCP can be installed as a Pi package. The package starts this MCP server over stdio and exposes convenient Pi tools that wrap the existing macOS-MCP tools.

One-line global setup:

  pi install git:github.com/CursorTouch/MacOS-MCP

After install, restart Pi or run:

  /reload

Try without installing:

  pi -e git:github.com/CursorTouch/MacOS-MCP

Local checkout setup:

  git clone https://github.com/CursorTouch/MacOS-MCP.git

cd MacOS-MCP uv sync npm install pi

If you copied only the extension into another Pi project, run Pi from the macOS-MCP checkout or set:

  export MACOS_MCP_ROOT=/path/to/MacOS-MCP

The extension exposes these Pi tools:

Recommended agent workflow:

• Call mac_snapshot first.
• Use the coordinates returned by Snapshot with mac_click, mac_type, and mac_scroll.
• Use screenshots/vision only when Accessibility data is missing or ambiguous.

The extension auto-detects the macOS-MCP checkout when installed as a Pi package. If you use a manually copied extension, set MACOS_MCP_ROOT=/path/to/MacOS-MCP.

Tau Coding Agent

Tau does not ship with built-in MCP support. This repo includes a project-local Tau extension at .tau/extensions/macos-mcp/ that starts the macOS-MCP server over stdio and exposes Tau-native tools that wrap the existing macOS-MCP tools.

Local checkout setup:

  git clone https://github.com/CursorTouch/MacOS-MCP.git

cd MacOS-MCP uv sync tau

Tau auto-discovers project extensions under .tau/extensions/*/ when run from the checkout, and installs the extension's own dependencies (declared in manifest.json) automatically on first load. If Tau is already running, use /reload.

If you copied only the extension into another Tau project, run Tau from the macOS-MCP checkout or set:

  export MACOS_MCP_ROOT=/path/to/MacOS-MCP

The extension exposes these Tau tools:

| mac_wait | Wait for UI changes/