{
  "markdown": "[![MCP Toplist](https://mcptoplist.com/badge/glama%2FCursorTouch%2FMacOS-MCP.svg)](https://mcptoplist.com/server/glama%2FCursorTouch%2FMacOS-MCP)\n\n<!-- mcp-name: io.github.Jeomon/macos-mcp -->\n<div align=\"center\">\n  <h1>🍎 macOS-MCP</h1>\n\n  <a href=\"https://github.com/Jeomon/macos-mcp/blob/main/LICENSE\">\n    <img src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\">\n  </a>\n  <img src=\"https://img.shields.io/badge/python-3.11%2B-blue\" alt=\"Python\">\n  <img src=\"https://img.shields.io/badge/platform-macOS%2012%2B-blue\" alt=\"Platform: macOS 12+\">\n  <img src=\"https://img.shields.io/github/last-commit/Jeomon/macos-mcp\" alt=\"Last Commit\">\n\n</div>\n\n## Overview\n\n**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.\n\n## Supported Operating Systems\n\n- macOS 12 (Monterey)\n- macOS 13 (Ventura)\n- macOS 14 (Sonoma)\n- macOS 15 (Sequoia)\n- macOS 26 (Tahoe)\n\n## Key Features\n\n- **Works with Any LLM** (Vision Optional)  \n  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.\n\n- **Native macOS Integration**  \n  Interacts natively with macOS UI elements using the Accessibility API. Opens apps, controls windows, simulates user input, and captures desktop state without workarounds.\n\n- **Rich Toolset for Automation**  \n  Complete toolkit for keyboard/mouse operations, window management, UI state capture, interactive element extraction from the accessibility tree, and AppleScript execution.\n\n- **Lightweight and Open-Source**  \n  Minimal dependencies with full source code available under MIT license. Easy setup and deployment.\n\n- **Smart Context Awareness**  \n  Automatically detects application state (Launchpad, Control Center, Spotlight). Scans menu bar, dock, desktop, and system UI elements intelligently.\n\n- **Customizable and Extensible**  \n  Easily extend with custom tools or modify behavior to suit your specific automation needs.\n\n## Installation\n\n### Prerequisites\n\n- **Python**: 3.11 or later\n- **UV Package Manager**: Install with `pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`\n- **macOS**: 12 (Monterey) or later\n- **Accessibility Permissions**: Required for UI element interaction\n\n### Quick Start\n\nRun the server directly:\n\n```shell\nuvx macos-mcp\n\n# Or with SSE/Streamable HTTP for network access\nuvx macos-mcp --transport sse --host localhost --port 8000\nuvx macos-mcp --transport streamable-http --host localhost --port 8000\n```\n\nRun it as a background service that starts now and at every login:\n\n```shell\nmacos-mcp install\n\n# Or choose the HTTP transport and bind address explicitly\nmacos-mcp install --transport sse --host 127.0.0.1 --port 8000\n```\n\nThis installs a `launchd` Launch Agent at `~/Library/LaunchAgents/com.macos-mcp.server.plist`.\nUse `macos-mcp uninstall` to remove it. Logs are written to `~/.macos-mcp/server.log`\nand `~/.macos-mcp/server.error.log`.\n\n### Transport Options\n\n| Transport | Flag | Use Case |\n|---|---|---|\n| `stdio` (default) | `--transport stdio` | Direct connection from MCP clients like Claude Desktop, Cursor, etc. |\n| `sse` | `--transport sse --host HOST --port PORT` | Network-accessible via Server-Sent Events |\n| `streamable-http` | `--transport streamable-http --host HOST --port PORT` | Network-accessible via HTTP streaming (recommended for production) |\n\n### Grant Required Permissions\n\nmacOS-MCP requires **Accessibility** and **Screen Recording** permissions to function properly.\n\n#### Accessibility Permissions\n\n1. Open **System Settings** → **Privacy & Security** → **Accessibility**\n2. Click the lock icon and authenticate\n3. Add the following applications:\n   - Your terminal application (Terminal, iTerm2, VS Code, etc.)\n   - Python (typically `/usr/bin/python3` or the Python version managed by UV)\n   - UV (`~/.local/bin/uv` if installed locally, or the Python environment UV manages)\n4. Restart the terminal after granting permissions\n\n**For `uvx` users:** Grant permissions to your terminal application and Python, as `uvx` runs Python packages from UV's cache.\n\n**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.\n\nIf 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.\n\n#### Screen Recording Permissions\n\nThe `Snapshot` tool requires Screen Recording permissions to capture screenshots:\n\n1. Open **System Settings** → **Privacy & Security** → **Screen Recording**\n2. Click the lock icon and authenticate\n3. Add the same applications as above (terminal, Python, UV)\n4. Restart the terminal after granting permissions\n\n**Note:** If the `Snapshot` tool fails, verify both permissions are granted in System Settings.\n\n### Integration Options\n\n<details>\n  <summary><strong>Claude Desktop</strong></summary>\n\n  1. Install [Claude Desktop](https://claude.ai/download)\n\n  2. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n  ```json\n  {\n    \"mcpServers\": {\n      \"macos-mcp\": {\n        \"command\": \"uvx\",\n        \"args\": [\"macos-mcp\"]\n      }\n    }\n  }\n  ```\n\n  3. Restart Claude Desktop\n\n</details>\n\n<details>\n  <summary><strong>Claude Desktop (connecting to an HTTP server)</strong></summary>\n\n  Claude Desktop's `claude_desktop_config.json` only supports stdio-based server\n  entries. To connect to a running macOS-MCP HTTP server (e.g. one started with\n  `macos-mcp install --transport streamable-http`), use\n  [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a stdio-to-HTTP\n  bridge.\n\n  This is especially useful when running **multiple Claude Desktop instances**\n  (e.g. via [Parall](https://parall.app)) — a single persistent HTTP server\n  handles all of them, avoiding the overhead of spawning a separate `macos-mcp`\n  process per session.\n\n  **1. Start the HTTP server** (one-time setup):\n\n  ```shell\n  macos-mcp install --transport streamable-http --host 127.0.0.1 --port 8000\n  ```\n\n  **2. Configure Claude Desktop** to connect via `mcp-remote`:\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"macos-mcp\": {\n        \"command\": \"npx\",\n        \"args\": [\n          \"-y\",\n          \"mcp-remote\",\n          \"http://127.0.0.1:8000/mcp\",\n          \"--transport\",\n          \"http-only\"\n        ]\n      }\n    }\n  }\n  ```\n\n  **3. Restart Claude Desktop.**\n\n  If you have multiple Claude Desktop instances (e.g. Parall clones), add the\n  same `mcpServers` entry to each instance's `claude_desktop_config.json`. All\n  instances will share the single background server.\n\n  A migration script is included for bulk reconfiguration — see\n  [`scripts/stdio-to-http-reconfig.sh`](scripts/stdio-to-http-reconfig.sh).\n\n  **With authentication** (recommended when binding to `0.0.0.0`):\n\n  ```shell\n  # Start server with an auth key\n  macos-mcp install --transport streamable-http --host 0.0.0.0 --port 8000 \\\n    --auth-key \"your-secret-token\"\n  ```\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"macos-mcp\": {\n        \"command\": \"npx\",\n        \"args\": [\n          \"-y\",\n          \"mcp-remote\",\n          \"http://127.0.0.1:8000/mcp\",\n          \"--transport\",\n          \"http-only\",\n          \"--header\",\n          \"Authorization: Bearer your-secret-token\"\n        ]\n      }\n    }\n  }\n  ```\n\n</details>\n\n<details>\n  <summary><strong>Gemini CLI</strong></summary>\n\n  1. Install Gemini CLI:\n  ```shell\n  npm install -g @google/gemini-cli\n  ```\n\n  2. Navigate to `~/.gemini` and open `settings.json`\n\n  3. Add the server config:\n  ```json\n  {\n    \"theme\": \"Default\",\n    \"mcpServers\": {\n      \"macos-mcp\": {\n        \"command\": \"uvx\",\n        \"args\": [\"macos-mcp\"]\n      }\n    }\n  }\n  ```\n\n  4. Restart Gemini CLI\n\n</details>\n\n<details>\n  <summary><strong>Claude Code</strong></summary>\n\n  1. Install [Claude Code](https://claude.com/claude-code)\n\n  2. Add to your project configuration or use the MCP marketplace integration\n\n</details>\n\n<details>\n  <summary><strong>Pi Agent</strong></summary>\n\n  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.\n\n  **One-line global setup:**\n\n  ```shell\n  pi install git:github.com/CursorTouch/MacOS-MCP\n  ```\n\n  After install, restart Pi or run:\n\n  ```text\n  /reload\n  ```\n\n  **Try without installing:**\n\n  ```shell\n  pi -e git:github.com/CursorTouch/MacOS-MCP\n  ```\n\n  **Local checkout setup:**\n\n  ```shell\n  git clone https://github.com/CursorTouch/MacOS-MCP.git\n  cd MacOS-MCP\n  uv sync\n  npm install\n  pi\n  ```\n\n  If you copied only the extension into another Pi project, run Pi from the macOS-MCP checkout or set:\n\n  ```shell\n  export MACOS_MCP_ROOT=/path/to/MacOS-MCP\n  ```\n\n  The extension exposes these Pi tools:\n\n  | Pi Tool | Purpose |\n  |---------|---------|\n  | `mac_snapshot` | Read current macOS UI state through the existing Snapshot tool. |\n  | `mac_app` | Launch, switch, move, or resize macOS applications/windows. |\n  | `mac_click` | Click coordinates returned by `mac_snapshot`. |\n  | `mac_type` | Type text at coordinates returned by `mac_snapshot`. |\n  | `mac_shortcut` | Run keyboard shortcuts such as `command+c` or `command+space`. |\n  | `mac_scroll` | Scroll at the current pointer or coordinates. |\n  | `mac_wait` | Wait for UI changes/loading. |\n\n  Recommended agent workflow:\n  - Call `mac_snapshot` first.\n  - Use the coordinates returned by Snapshot with `mac_click`, `mac_type`, and `mac_scroll`.\n  - Use screenshots/vision only when Accessibility data is missing or ambiguous.\n\n  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`.\n\n</details>\n\n<details>\n  <summary><strong>Tau Coding Agent</strong></summary>\n\n  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.\n\n  **Local checkout setup:**\n\n  ```shell\n  git clone https://github.com/CursorTouch/MacOS-MCP.git\n  cd MacOS-MCP\n  uv sync\n  tau\n  ```\n\n  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`.\n\n  If you copied only the extension into another Tau project, run Tau from the macOS-MCP checkout or set:\n\n  ```shell\n  export MACOS_MCP_ROOT=/path/to/MacOS-MCP\n  ```\n\n  The extension exposes these Tau tools:\n\n  | Tau Tool | Purpose |\n  |----------|---------|\n  | `mac_snapshot` | Read current macOS UI state through the existing Snapshot tool. |\n  | `mac_app` | Launch, switch, or resize macOS applications/windows. |\n  | `mac_click` | Click coordinates returned by `mac_snapshot`. |\n  | `mac_type` | Type text at coordinates returned by `mac_snapshot`. |\n  | `mac_shortcut` | Run keyboard shortcuts such as `command+c` or `command+space`. |\n  | `mac_scroll` | Scroll at the current pointer or coordinates. |\n  | `mac_wait` | Wait for UI changes/loading. |\n\n  Recommended agent workflow:\n  - Call `mac_snapshot` first.\n  - Use the coordinates returned by Snapshot with `mac_click`, `mac_type`, and `mac_scroll`.\n  - Use screenshots/vision only when Accessibility data is missing or ambiguous.\n\n  The extension auto-detects the macOS-MCP checkout. If you use a manually copied extension, set `MACOS_MCP_ROOT=/path/to/MacOS-MCP`.\n\n</details>\n\n<details>\n  <summary><strong>Other Integrations</strong></summary>\n\n  Any client supporting the Model Context Protocol can integrate macOS-MCP by configuring the `uvx macos-mcp` command in their MCP server settings.\n\n</details>\n\n---\n\n## MCP Tools\n\nmacOS-MCP provides a comprehensive toolset for desktop automation:\n\n| Tool | Purpose |\n|------|---------|\n| **Click** | Click at coordinates with support for left, right, and double-click |\n| **Type** | Type text at cursor position, optionally clearing existing text |\n| **Scroll** | Scroll vertically or horizontally in focused window or regions |\n| **Move** | Move mouse pointer or drag to coordinates |\n| **Shortcut** | Press keyboard shortcuts (Cmd+C, Cmd+Tab, etc.) |\n| **App** | Launch applications, manage windows (resize/move), switch between apps. Supports app names and bundle IDs |\n| **Desktop** | Create a new Mission Control Space (virtual desktop) via Accessibility, verifying the space count increased |\n| **Shell** | Execute commands or AppleScript. Use `mode='osascript'` for AppleScript |\n| **Scrape** | Extract and convert webpage content to Markdown format |\n| **Wait** | Pause execution for a defined duration |\n\n## Limitations\n\n- **Accessibility Requirements**: Manual permission grant required in System Preferences\n- **App Compatibility**: Some applications have limited or no Accessibility API support\n- **Performance Variance**: Complex UIs with many elements may have slower traversal\n- **Text Input**: Some specialized input fields may not properly receive keystrokes\n- **Authentication**: Cannot interact with system authentication dialogs\n\n## Security & Access Control\n\n### Authentication\n```shell\nmacos-mcp --transport sse --host 0.0.0.0 --auth-key \"your_token\"\n```\nRequires `Authorization: Bearer your_token` header on all requests.\n\n### IP Allowlist\n```shell\nmacos-mcp --auth-key \"token\" --ip-allowlist \"203.0.113.0/24,198.51.100.5\"\n```\nRestricts connections to specified CIDR ranges.\n\n### TLS/HTTPS\n```shell\nopenssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes\n\nmacos-mcp --ssl-certfile cert.pem --ssl-keyfile key.pem\n```\n\n### OAuth 2.0 + PKCE\n\nFor MCP clients that use OAuth (e.g. Claude Desktop) instead of a static API key:\n\n```shell\nmacos-mcp --transport streamable-http --host 0.0.0.0 \\\n  --ssl-certfile ~/.macos-mcp/cert.pem \\\n  --ssl-keyfile  ~/.macos-mcp/key.pem \\\n  --oauth-client-id my-client \\\n  --oauth-client-secret my-secret\n```\n\n**Claude Desktop config** (via `mcp-remote` bridge — see [Integration Options](#integration-options)):\n```json\n{\n  \"mcpServers\": {\n    \"macos-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://<host>:8000/mcp\",\n        \"--transport\",\n        \"http-only\"\n      ]\n    }\n  }\n}\n```\n\n> **Note:** Claude Desktop's `claude_desktop_config.json` does not support\n> `\"type\": \"http\"` or `\"url\"` entries directly. Use `mcp-remote` as shown\n> above, or add the server via **Settings → Connectors → Add custom connector**\n> in the Claude Desktop UI.\n\nThe OAuth server exposes:\n- `GET /.well-known/oauth-authorization-server` — server metadata (RFC 8414)\n- `GET /oauth/authorize` — Authorization Code + PKCE (`S256` required)\n- `POST /oauth/token` — token exchange (client secret required)\n- `POST /oauth/register` — disabled; clients must be pre-provisioned\n\nDynamic client registration is disabled. Redirect URIs must be loopback `http(s)` only.\nAuth key and OAuth can coexist — both are accepted as valid Bearer tokens.\n\n### SSRF Protection\nThe `Scrape` tool blocks: private IPs, loopback, link-local, credentials-in-URLs, non-HTTP schemes.\n\n### Config File (`~/.macos-mcp/config.toml`)\n\nInstead of passing flags every time, store your configuration in `~/.macos-mcp/config.toml`. CLI flags always override config file values.\n\n**Search order:**\n1. `--config /path/to/config.toml`\n2. `~/.macos-mcp/config.toml`\n\n**stdio** — local only, no security needed:\n```toml\n[server]\ntransport = \"stdio\"\n```\n\n**SSE** — network access with auth and IP restriction:\n```toml\n[server]\ntransport = \"sse\"\nhost      = \"0.0.0.0\"\nport      = 8000\nauth_key  = \"your-secret-key\"\n\n[security]\nip_allowlist = [\"192.168.1.0/24\"]\n```\n\n**Streamable HTTP** — network access with auth and TLS (recommended for production):\n```toml\n[server]\ntransport    = \"streamable-http\"\nhost         = \"0.0.0.0\"\nport         = 8000\nauth_key     = \"your-secret-key\"\nssl_certfile = \"cert.pem\"   # resolved relative to ~/.macos-mcp/\nssl_keyfile  = \"key.pem\"\n\n[security]\nip_allowlist        = [\"192.168.1.0/24\"]\noauth_client_id     = \"my-client\"      # optional — enables OAuth 2.0 + PKCE\noauth_client_secret = \"my-secret\"\n\n[tools]\nexclude = [\"Shell\", \"Scrape\"]   # disable specific tools\n```\n\nAvailable tool names: `App`, `Shell`, `Snapshot`, `Click`, `Type`, `Scroll`, `Move`, `Shortcut`, `Wait`, `Scrape`, `Notification`\n\nPlace your cert and key files in the same directory:\n\n```\n~/.macos-mcp/\n├── config.toml\n├── cert.pem\n└── key.pem\n```\n\nGenerate a self-signed cert directly into that directory:\n\n```shell\nmkdir -p ~/.macos-mcp\nopenssl req -x509 -newkey rsa:4096 \\\n  -keyout ~/.macos-mcp/key.pem \\\n  -out ~/.macos-mcp/cert.pem \\\n  -days 365 -nodes\n```\n\n---\n\n## Environment Variables\n\nAll variables are optional. Set them via the `env` key in `claude_desktop_config.json`.\n\n| Variable | Default | Description |\n|---|---|---|\n| `ANONYMIZED_TELEMETRY` | `true` | Set to `false` to disable anonymous usage telemetry. No personal data, tool arguments, or outputs are ever collected. |\n| `MACOS_MCP_AUTH_KEY` | _(none)_ | Bearer token required on all HTTP requests. Alternative to `--auth-key` CLI flag. |\n| `MACOS_MCP_IP_ALLOWLIST` | _(none)_ | Comma-separated list of allowed client IPs or CIDR ranges. Alternative to `--ip-allowlist` CLI flag. |\n| `MACOS_MCP_SSL_CERTFILE` | _(none)_ | Path to TLS certificate file (.pem). Must be provided with `MACOS_MCP_SSL_KEYFILE`. |\n| `MACOS_MCP_SSL_KEYFILE` | _(none)_ | Path to TLS private key file (.pem). Must be provided with `MACOS_MCP_SSL_CERTFILE`. |\n\n**Example `claude_desktop_config.json` (remote with auth + TLS):**\n```json\n{\n  \"mcpServers\": {\n    \"macos-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"macos-mcp\", \"--transport\", \"sse\", \"--host\", \"0.0.0.0\"],\n      \"env\": {\n        \"MACOS_MCP_AUTH_KEY\": \"your_token\",\n        \"MACOS_MCP_IP_ALLOWLIST\": \"203.0.113.0/24\",\n        \"MACOS_MCP_SSL_CERTFILE\": \"/path/to/cert.pem\",\n        \"MACOS_MCP_SSL_KEYFILE\": \"/path/to/key.pem\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Telemetry\n\nmacOS-MCP collects anonymous usage data to help improve the server. No personal information, tool arguments, or outputs are tracked.\n\nTo disable telemetry, set `ANONYMIZED_TELEMETRY` to `false`:\n\n```json\n{\n  \"mcpServers\": {\n    \"macos-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"macos-mcp\"],\n      \"env\": { \"ANONYMIZED_TELEMETRY\": \"false\" }\n    }\n  }\n}\n```\n\n---\n\n## Security\n\n⚠️ **Important Security Notice**: macOS-MCP operates with full Accessibility API permissions and executes real system operations without sandboxing. It can perform permanent, irreversible actions.\n\n**Before using macOS-MCP:**\n\n- ✅ Grant Accessibility permissions only to trusted applications\n- ✅ Understand that Shell commands execute with full user privileges\n- ✅ Review AI-generated action plans before execution\n- ✅ Use only in virtual machines or isolated environments with valueless data\n- ✅ Create backups before testing in production-like scenarios\n\n**⛔ Do NOT use on:**\n- Systems with irreplaceable data\n- Production machines or shared systems\n- Compliance-regulated environments (HIPAA, PCI, etc.)\n\nFor detailed security guidance, see [SECURITY.md](SECURITY.md).\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:\n- Development setup and code standards\n- Testing requirements\n- Pull request process\n- Coding conventions (Ruff formatting, 100 char line length)\n\n## License\n\nmacOS-MCP is licensed under the MIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgements\n\nmacOS-MCP is built with excellent open-source projects:\n\n- [PyObjC](https://pyobjc.readthedocs.io/) - Python to Objective-C bridge\n- [Pillow](https://pillow.readthedocs.io/) - Python Imaging Library\n- [FastMCP](https://github.com/jlowin/fastmcp) - MCP framework\n- macOS Accessibility API (ApplicationServices)\n\n## Citation\n\nIf you use macOS-MCP in your research or project, please cite:\n\n```bibtex\n@software{macos-mcp,\n  author       = {Jeomon George},\n  title        = {macOS-MCP: Lightweight MCP Server for macOS Automation},\n  year         = {2025},\n  publisher    = {GitHub},\n  url          = {https://github.com/Jeomon/macos-mcp}\n}\n```\n\n---\n\n**Questions or Issues?** [Open an issue](https://github.com/Jeomon/macos-mcp/issues) or check [SECURITY.md](SECURITY.md) for security concerns.\n",
  "bytes": 21178,
  "sha": "e2943d7c64d17f0fc868aa0baf59c2f0f36afda787131ed90450134353acd5fa",
  "repo_slug": "jeomon/macos-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jeomon_macos_mcp_09ed0b15/readme"
}