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

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/cursortouch-macos-mcp
Generated for open source discovery and AI-assisted research.

MacOS-MCP is a lightweight, open-source Model Context Protocol server designed to bridge AI agents with the macOS operating system. It enables seamless automation of macOS tasks such as file navigation, application control, and UI interaction through large language models, without requiring computer vision or specialized setups. This project provides a robust toolkit for AI-driven desktop automation.

GitHub: https://github.com/CursorTouch/MacOS-MCP
OSRepos URL: https://osrepos.com/repo/cursortouch-macos-mcp

## Summary

MacOS-MCP is a lightweight, open-source Model Context Protocol server designed to bridge AI agents with the macOS operating system. It enables seamless automation of macOS tasks such as file navigation, application control, and UI interaction through large language models, without requiring computer vision or specialized setups. This project provides a robust toolkit for AI-driven desktop automation.

## Topics

- macos
- mcp-server
- python
- ai-automation
- llm-tools
- desktop-automation
- open-source

## Repository Information

Last analyzed by OSRepos: Wed Jul 08 2026 16:34:37 GMT+0100 (Western European Summer Time)
Detail views: 1
GitHub clicks: 0

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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:

shell
uvx macos-mcp


For network access, use specific transport options:

shell
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:

shell
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:**

shell
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:**

shell
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](https://github.com/CursorTouch/MacOS-MCP){:target="_blank"}
*   **License (MIT)**: [https://github.com/CursorTouch/MacOS-MCP/blob/main/LICENSE](https://github.com/CursorTouch/MacOS-MCP/blob/main/LICENSE){:target="_blank"}
*   **Contributing Guide**: [https://github.com/CursorTouch/MacOS-MCP/blob/main/CONTRIBUTING.md](https://github.com/CursorTouch/MacOS-MCP/blob/main/CONTRIBUTING.md){:target="_blank"}
*   **Security Information**: [https://github.com/CursorTouch/MacOS-MCP/blob/main/SECURITY.md](https://github.com/CursorTouch/MacOS-MCP/blob/main/SECURITY.md){:target="_blank"}