# macOS-MCP

An MCP server that lets an agent drive macOS: launch apps, click UI elements, capture the desktop state.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 223
- Author: CursorTouch
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/CursorTouch/MacOS-MCP
- Updated: 2026-10-12
- HTML: https://affpapa.org/en/nevibecode/mcp/macos-mcp

## What it does

macOS-MCP bridges an AI agent and the macOS desktop through the Accessibility API. The agent opens applications, moves windows, simulates keyboard and mouse input, pulls interactive elements from the accessibility tree, and runs AppleScript. The `Snapshot` tool captures screenshots through Screen Recording. No computer vision needed, because the server hands the agent interface structure rather than pixels.

Run it straight away with `uvx macos-mcp` over stdio, or switch to the `sse` or `streamable-http` transport bound to `localhost` and a port. The `macos-mcp install` command writes a Launch Agent to `~/Library/LaunchAgents/com.macos-mcp.server.plist` so the server starts at every login; logs go to `~/.macos-mcp/`. Both HTTP transports expose the server to the network, not just the local machine.

You need Python 3.11 or later, UV, and macOS 12+. Without Accessibility and Screen Recording granted in System Settings the tools will refuse to work: grant both to your terminal, Python and UV, then restart the terminal. If a UV-managed interpreter stays greyed out in the picker, just start the server — it calls `AXIsProcessTrustedWithOptions` on startup and macOS shows its own consent dialog.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add macos-mcp -- uvx macos-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add macos-mcp -- uvx macos-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "macos-mcp": {
            "command": "uvx",
            "args": [
                "macos-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "macos-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "macos-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add macos-mcp uvx macos-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from macos-mcp <command>

## When to use it
- open an app and focus the right window from the agent
- list clickable elements of a window instead of parsing a screenshot
- run an AppleScript the agent asks for mid-chat
- keep the automation server running at every login

## Example prompts
- Open Finder and go to `~/Projects`, then show me what's inside
- Take a snapshot of the screen and tell me which window is active
- Run an AppleScript that closes all Safari windows

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md