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.
MCP server for computer use in MacOS
星數
226
工具
—
可用率
—
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
# Or with SSE/Streamable HTTP for network access
uvx macos-mcp --transport sse --host localhost --port 8000
uvx macos-mcp --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
Transport
Flag
Use Case
stdio (default)
--transport stdio
Direct connection from MCP clients like Claude Desktop, Cursor, etc.
sse
--transport sse --host HOST --port PORT
Network-accessible via Server-Sent Events
streamable-http
--transport streamable-http --host HOST --port PORT
Network-accessible via HTTP streaming (recommended for production)
Grant Required Permissions
macOS-MCP requires Accessibility and Screen Recording permissions to function properly.
Accessibility Permissions
Open System Settings → Privacy & Security → Accessibility
Click the lock icon and authenticate
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)
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:
Open System Settings → Privacy & Security → Screen Recording
Click the lock icon and authenticate
Add the same applications as above (terminal, Python, UV)
Restart the terminal after granting permissions
Note: If the Snapshot tool fails, verify both permissions are granted in System Settings.
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.
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.
Add to your project configuration or use the MCP marketplace integration
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:
Pi Tool
Purpose
mac_snapshot
Read current macOS UI state through the existing Snapshot tool.
mac_app
Launch, switch, move, or resize macOS applications/windows.
mac_click
Click coordinates returned by mac_snapshot.
mac_type
Type text at coordinates returned by mac_snapshot.
mac_shortcut
Run keyboard shortcuts such as command+c or command+space.
mac_scroll
Scroll at the current pointer or coordinates.
mac_wait
Wait for UI changes/loading.
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 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:
Tau Tool
Purpose
mac_snapshot
Read current macOS UI state through the existing Snapshot tool.
mac_app
Launch, switch, or resize macOS applications/windows.
mac_click
Click coordinates returned by mac_snapshot.
mac_type
Type text at coordinates returned by mac_snapshot.
mac_shortcut
Run keyboard shortcuts such as command+c or command+space.
mac_scroll
Scroll at the current pointer or coordinates.
mac_wait
Wait for UI changes/loading.
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. If you use a manually copied extension, set MACOS_MCP_ROOT=/path/to/MacOS-MCP.
Any client supporting the Model Context Protocol can integrate macOS-MCP by configuring the uvx macos-mcp command in their MCP server settings.
MCP Tools
macOS-MCP provides a comprehensive toolset for desktop automation:
Tool
Purpose
Click
Click at coordinates with support for left, right, and double-click
Type
Type text at cursor position, optionally clearing existing text
Scroll
Scroll vertically or horizontally in focused window or regions
Move
Move mouse pointer or drag to coordinates
Shortcut
Press keyboard shortcuts (Cmd+C, Cmd+Tab, etc.)
App
Launch applications, manage windows (resize/move), switch between apps. Supports app names and bundle IDs
Desktop
Create a new Mission Control Space (virtual desktop) via Accessibility, verifying the space count increased
Shell
Execute commands or AppleScript. Use mode='osascript' for AppleScript
Scrape
Extract and convert webpage content to Markdown format
Wait
Pause execution for a defined duration
Limitations
Accessibility Requirements: Manual permission grant required in System Preferences
App Compatibility: Some applications have limited or no Accessibility API support
Performance Variance: Complex UIs with many elements may have slower traversal
Text Input: Some specialized input fields may not properly receive keystrokes
Authentication: Cannot interact with system authentication dialogs
Note: Claude Desktop's claude_desktop_config.json does not support
"type": "http" or "url" entries directly. Use mcp-remote as shown
above, or add the server via Settings → Connectors → Add custom connector
in the Claude Desktop UI.
The OAuth server exposes:
GET /.well-known/oauth-authorization-server — server metadata (RFC 8414)
GET /oauth/authorize — Authorization Code + PKCE (S256 required)
POST /oauth/token — token exchange (client secret required)
POST /oauth/register — disabled; clients must be pre-provisioned
Dynamic client registration is disabled. Redirect URIs must be loopback http(s) only.
Auth key and OAuth can coexist — both are accepted as valid Bearer tokens.
⚠️ Important Security Notice: macOS-MCP operates with full Accessibility API permissions and executes real system operations without sandboxing. It can perform permanent, irreversible actions.
Before using macOS-MCP:
✅ Grant Accessibility permissions only to trusted applications
✅ Understand that Shell commands execute with full user privileges
✅ Review AI-generated action plans before execution
✅ Use only in virtual machines or isolated environments with valueless data
✅ Create backups before testing in production-like scenarios