MacOS-MCP: Lightweight MCP Server for AI Automation on macOS

Introduction

MacOS-MCP is an open-source, lightweight Model Context Protocol (MCP) server that empowers AI agents to interact seamlessly with the macOS operating system. It acts as a bridge, allowing large language models (LLMs) to automate a wide range of macOS tasks, including file navigation, application control, UI interaction, browser automation, and general system operations. Unlike many traditional automation tools, MacOS-MCP leverages the native macOS Accessibility API, eliminating the need for computer vision, fine-tuned models, or specialized setups, making it compatible with any LLM.

Installation

Getting started with MacOS-MCP involves a few prerequisites and simple steps.

Prerequisites

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

Quick Start

You can run the server directly from your terminal:

uvx macos-mcp

For network access, use specific transport options:

uvx macos-mcp --transport sse --host localhost --port 8000
# Or for production-ready HTTP streaming
uvx macos-mcp --transport streamable-http --host localhost --port 8000

To install it as a background service that starts at login:

macos-mcp install

Grant Required Permissions

MacOS-MCP requires Accessibility and Screen Recording permissions. Navigate to System Settings ? Privacy & Security and grant access to your terminal application, Python, and UV under both Accessibility and Screen Recording. The server can also prompt for Accessibility permissions on startup.

Examples

MacOS-MCP is designed for integration with various AI agent platforms. Here are a couple of examples demonstrating its use:

Pi Agent Integration

MacOS-MCP can be installed as a Pi package, exposing convenient Pi tools that wrap the existing macOS-MCP functionalities.

One-line global setup:

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

After installation, restart Pi or run /reload.

The extension exposes tools like mac_snapshot (to read UI state), mac_app (to manage applications), mac_click (to click coordinates), mac_type (to type text), mac_shortcut (to run keyboard shortcuts), and mac_scroll (to scroll). The recommended workflow is to call mac_snapshot first and then use its returned coordinates with other tools.

Tau Coding Agent Integration

This repository includes a project-local Tau extension that starts the macOS-MCP server and exposes Tau-native tools.

Local checkout setup:

git clone https://github.com/CursorTouch/MacOS-MCP.git
cd MacOS-MCP
uv sync
tau

Tau auto-discovers project extensions. Similar to Pi, it provides tools like mac_snapshot, mac_app, mac_click, mac_type, mac_shortcut, and mac_scroll for interacting with macOS.

Other integrations include Claude Desktop, Gemini CLI, and Claude Code, all configurable via their respective MCP server settings.

Why Use MacOS-MCP?

MacOS-MCP offers several compelling advantages for AI-driven macOS automation:

• LLM Agnostic: Works seamlessly with any LLM, including Claude, GPT, and Gemini, without requiring specialized models or computer vision.
• Native macOS Integration: Interacts directly with macOS UI elements using the Accessibility API, allowing for robust control over applications, windows, and user input.
• Rich Toolset: Provides a comprehensive suite of tools for keyboard/mouse operations, window management, UI state capture, interactive element extraction, and AppleScript execution.
• Lightweight and Open-Source: Minimal dependencies, full source code available under the MIT license, ensuring easy setup and customizability.
• Smart Context Awareness: Intelligently detects application states and scans system UI elements like the menu bar, dock, and desktop.
• Security Features: Includes options for authentication (Bearer token), IP allowlisting, TLS/HTTPS, and OAuth 2.0 + PKCE, allowing for secure deployment in network environments.

Links

For more detailed information, contributions, or to report issues, please refer to the official repository and documentation:

• GitHub Repository: https://github.com/CursorTouch/MacOS-MCP
• License (MIT): https://github.com/CursorTouch/MacOS-MCP/blob/main/LICENSE
• Contributing Guide: https://github.com/CursorTouch/MacOS-MCP/blob/main/CONTRIBUTING.md
• Security Information: https://github.com/CursorTouch/MacOS-MCP/blob/main/SECURITY.md