Skip to content
Back to search

MacOS-MCP

Lightweight MCP server for computer use in MacOS

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cursortouch--macos-mcp/badge.svg)](/listings/cursortouch--macos-mcp)

HTML

<a href="/listings/cursortouch--macos-mcp"><img src="/api/listings/cursortouch--macos-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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

1. Open **System Settings** → **Privacy & Security** → **Accessibility** 2. Click the lock icon and authenticate 3. 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) 4. 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:

1. Open **System Settings** → **Privacy & Security** → **Screen Recording** 2. Click the lock icon and authenticate 3. Add the same applications as above (terminal, Python, UV) 4. Restart the terminal after granting permissions

**Note:** If the `Snapshot` tool fails, verify both permissions are granted in System Settings.

Integration Options

<details> <summary><strong>Claude Desktop</strong></summary>

1. Install [Claude Desktop](https://claude.ai/download)

2. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

  {
    "mcpServers": {
      "macos-mcp": {
        "command": "uvx",
        "args": ["macos-mcp"]
      }
    }
  }

3. Restart Claude Desktop

</details>

<details> <summary><strong>Claude Desktop (connecting to an HTTP server)</strong></summary>

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 638 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [![MCP Toplist](https://mcptoplist.com/badge/glama%2FCursorTouch%2FMacOS-MCP.svg)](https://mcptoplist.com/server/glama%2FCursorTouch%2FMacOS-MCP)
  2. <!-- mcp-name: io.github.Jeomon/macos-mcp -->
  3. <div align="center">
  4. <h1>🍎 macOS-MCP</h1>
  5. <a href="https://github.com/Jeomon/macos-mcp/blob/main/LICENSE">
  6. <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  7. </a>
  8. <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python">
  9. <img src="https://img.shields.io/badge/platform-macOS%2012%2B-blue" alt="Platform: macOS 12+">
  10. <img src="https://img.shields.io/github/last-commit/Jeomon/macos-mcp" alt="Last Commit">
  11. </div>
  12. ## Overview
  13. **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.
  14. ## Supported Operating Systems
  15. - macOS 12 (Monterey)
  16. - macOS 13 (Ventura)
  17. - macOS 14 (Sonoma)
  18. - macOS 15 (Sequoia)
  19. - macOS 26 (Tahoe)
  20. ## Key Features
  21. - **Works with Any LLM** (Vision Optional)
  22. 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.
  23. - **Native macOS Integration**
  24. Interacts natively with macOS UI elements using the Accessibility API. Opens apps, controls windows, simulates user input, and captures desktop state without workarounds.
  25. - **Rich Toolset for Automation**
  26. Complete toolkit for keyboard/mouse operations, window management, UI state capture, interactive element extraction from the accessibility tree, and AppleScript execution.
  27. - **Lightweight and Open-Source**
  28. Minimal dependencies with full source code available under MIT license. Easy setup and deployment.
  29. - **Smart Context Awareness**
  30. Automatically detects application state (Launchpad, Control Center, Spotlight). Scans menu bar, dock, desktop, and system UI elements intelligently.
  31. - **Customizable and Extensible**
  32. Easily extend with custom tools or modify behavior to suit your specific automation needs.
  33. ## Installation
  34. ### Prerequisites
  35. - **Python**: 3.11 or later
  36. - **UV Package Manager**: Install with `pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`
  37. - **macOS**: 12 (Monterey) or later
  38. - **Accessibility Permissions**: Required for UI element interaction
  39. ### Quick Start
  40. Run the server directly:
  41. ```shell
  42. uvx macos-mcp serve
  43. # Or with SSE/Streamable HTTP for network access
  44. uvx macos-mcp serve --transport sse --host localhost --port 8000
  45. uvx macos-mcp serve --transport streamable-http --host localhost --port 8000
  46. ```
  47. Run it as a background service that starts now and at every login:
  48. ```shell
  49. macos-mcp install
  50. # Or choose the HTTP transport and bind address explicitly
  51. macos-mcp install --transport sse --host 127.0.0.1 --port 8000
  52. ```
  53. This installs a `launchd` Launch Agent at `~/Library/LaunchAgents/com.macos-mcp.server.plist`.
  54. Use `macos-mcp uninstall` to remove it. Logs are written to `~/.macos-mcp/server.log`
  55. and `~/.macos-mcp/server.error.log`.
  56. ### Transport Options
  57. | Transport | Flag | Use Case |
  58. |---|---|---|
  59. | `stdio` (default) | `--transport stdio` | Direct connection from MCP clients like Claude Desktop, Cursor, etc. |
  60. | `sse` | `--transport sse --host HOST --port PORT` | Network-accessible via Server-Sent Events |
  61. | `streamable-http` | `--transport streamable-http --host HOST --port PORT` | Network-accessible via HTTP streaming (recommended for production) |
  62. ### Grant Required Permissions
  63. macOS-MCP requires **Accessibility** and **Screen Recording** permissions to function properly.
  64. #### Accessibility Permissions
  65. 1. Open **System Settings** → **Privacy & Security** → **Accessibility**
  66. 2. Click the lock icon and authenticate
  67. 3. Add the following applications:
  68. - Your terminal application (Terminal, iTerm2, VS Code, etc.)
  69. - Python (typically `/usr/bin/python3` or the Python version managed by UV)
  70. - UV (`~/.local/bin/uv` if installed locally, or the Python environment UV manages)
  71. 4. Restart the terminal after granting permissions
  72. **For `uvx` users:** Grant permissions to your terminal application and Python, as `uvx` runs Python packages from UV's cache.
  73. **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.
  74. 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.
  75. #### Screen Recording Permissions
  76. The `Snapshot` tool requires Screen Recording permissions to capture screenshots:
  77. 1. Open **System Settings** → **Privacy & Security** → **Screen Recording**
  78. 2. Click the lock icon and authenticate
  79. 3. Add the same applications as above (terminal, Python, UV)
  80. 4. Restart the terminal after granting permissions
  81. **Note:** If the `Snapshot` tool fails, verify both permissions are granted in System Settings.
  82. ### Integration Options
  83. <details>
  84. <summary><strong>Claude Desktop</strong></summary>
  85. 1. Install [Claude Desktop](https://claude.ai/download)
  86. 2. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
  87. ```json
  88. {
  89. "mcpServers": {
  90. "macos-mcp": {
  91. "command": "uvx",
  92. "args": ["macos-mcp", "serve"]
  93. }
  94. }
  95. }
  96. ```
  97. 3. Restart Claude Desktop
  98. </details>
  99. <details>
  100. <summary><strong>Claude Desktop (connecting to an HTTP server)</strong></summary>
  101. Claude Desktop's `claude_desktop_config.json` only supports stdio-based server
  102. entries. To connect to a running macOS-MCP HTTP server (e.g. one started with
  103. `macos-mcp install --transport streamable-http`), use
  104. [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a stdio-to-HTTP
  105. bridge.
  106. This is especially useful when running **multiple Claude Desktop instances**
  107. (e.g. via [Parall](https://parall.app)) — a single persistent HTTP server
  108. handles all of them, avoiding the overhead of spawning a separate `macos-mcp`
  109. process per session.
  110. **1. Start the HTTP server** (one-time setup):
  111. ```shell
  112. macos-mcp install --transport streamable-http --host 127.0.0.1 --port 8000
  113. ```
  114. **2. Configure Claude Desktop** to connect via `mcp-remote`:
  115. ```json
  116. {
  117. "mcpServers": {
  118. "macos-mcp": {
  119. "command": "npx",
  120. "args": [
  121. "-y",
  122. "mcp-remote",
  123. "http://127.0.0.1:8000/mcp",
  124. "--transport",
  125. "http-only"
  126. ]
  127. }
  128. }
  129. }
  130. ```
  131. **3. Restart Claude Desktop.**
  132. If you have multiple Claude Desktop instances (e.g. Parall clones), add the
  133. same `mcpServers` entry to each instance's `claude_desktop_config.json`. All
  134. instances will share the single background server.
  135. A migration script is included for bulk reconfiguration — see
  136. [`scripts/stdio-to-http-reconfig.sh`](scripts/stdio-to-http-reconfig.sh).
  137. **With authentication** (recommended when binding to `0.0.0.0`):
  138. ```shell
  139. # Start server with an auth key
  140. macos-mcp install --transport streamable-http --host 0.0.0.0 --port 8000 \
  141. --auth-key "your-secret-token"
  142. ```
  143. ```json
  144. {
  145. "mcpServers": {
  146. "macos-mcp": {
  147. "command": "npx",
  148. "args": [
  149. "-y",
  150. "mcp-remote",
  151. "http://127.0.0.1:8000/mcp",
  152. "--transport",
  153. "http-only",
  154. "--header",
  155. "Authorization: Bearer your-secret-token"
  156. ]
  157. }
  158. }
  159. }
  160. ```
  161. </details>
  162. <details>
  163. <summary><strong>Gemini CLI</strong></summary>
  164. 1. Install Gemini CLI:
  165. ```shell
  166. npm install -g @google/gemini-cli
  167. ```
  168. 2. Navigate to `~/.gemini` and open `settings.json`
  169. 3. Add the server config:
  170. ```json
  171. {
  172. "theme": "Default",
  173. "mcpServers": {
  174. "macos-mcp": {
  175. "command": "uvx",
  176. "args": ["macos-mcp", "serve"]
  177. }
  178. }
  179. }
  180. ```
  181. 4. Restart Gemini CLI
  182. </details>
  183. <details>
  184. <summary><strong>Claude Code</strong></summary>
  185. 1. Install [Claude Code](https://claude.com/claude-code)
  186. 2. Add to your project configuration or use the MCP marketplace integration
  187. </details>
  188. <details>
  189. <summary><strong>Pi Agent</strong></summary>
  190. 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.
  191. **One-line global setup:**
  192. ```shell
  193. pi install git:github.com/CursorTouch/MacOS-MCP
  194. ```
  195. After install, restart Pi or run:
  196. ```text
  197. /reload
  198. ```
  199. **Try without installing:**
  200. ```shell
  201. pi -e git:github.com/CursorTouch/MacOS-MCP
  202. ```
  203. **Local checkout setup:**
  204. ```shell
  205. git clone https://github.com/CursorTouch/MacOS-MCP.git
  206. cd MacOS-MCP
  207. uv sync
  208. npm install
  209. pi
  210. ```
  211. If you copied only the extension into another Pi project, run Pi from the macOS-MCP checkout or set:
  212. ```shell
  213. export MACOS_MCP_ROOT=/path/to/MacOS-MCP
  214. ```
  215. The extension exposes these Pi tools:
  216. | Pi Tool | Purpose |
  217. |---------|---------|
  218. | `mac_snapshot` | Read current macOS UI state through the existing Snapshot tool. |
  219. | `mac_app` | Launch, switch, move, or resize macOS applications/windows. |
  220. | `mac_click` | Click coordinates returned by `mac_snapshot`. |
  221. | `mac_type` | Type text at coordinates returned by `mac_snapshot`. |
  222. | `mac_shortcut` | Run keyboard shortcuts such as `command+c` or `command+space`. |
  223. | `mac_scroll` | Scroll at the current pointer or coordinates. |
  224. | `mac_wait` | Wait for UI changes/loading. |
  225. Recommended agent workflow:
  226. - Call `mac_snapshot` first.
  227. - Use the coordinates returned by Snapshot with `mac_click`, `mac_type`, and `mac_scroll`.
  228. - Use screenshots/vision only when Accessibility data is missing or ambiguous.
  229. 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`.
  230. </details>
  231. <details>
  232. <summary><strong>Tau Coding Agent</strong></summary>
  233. 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.
  234. **Local checkout setup:**
  235. ```shell
  236. git clone https://github.com/CursorTouch/MacOS-MCP.git
  237. cd MacOS-MCP
  238. uv sync
  239. tau
  240. ```
  241. 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`.
  242. If you copied only the extension into another Tau project, run Tau from the macOS-MCP checkout or set:
  243. ```shell
  244. export MACOS_MCP_ROOT=/path/to/MacOS-MCP
  245. ```
  246. The extension exposes these Tau tools:
  247. | Tau Tool | Purpose |
  248. |----------|---------|
  249. | `mac_snapshot` | Read current macOS UI state through the existing Snapshot tool. |
  250. | `mac_app` | Launch, switch, or resize macOS applications/windows. |
  251. | `mac_click` | Click coordinates returned by `mac_snapshot`. |
  252. | `mac_type` | Type text at coordinates returned by `mac_snapshot`. |
  253. | `mac_shortcut` | Run keyboard shortcuts such as `command+c` or `command+space`. |
  254. | `mac_scroll` | Scroll at the current pointer or coordinates. |
  255. | `mac_wait` | Wait for UI changes/loading. |
  256. Recommended agent workflow:
  257. - Call `mac_snapshot` first.
  258. - Use the coordinates returned by Snapshot with `mac_click`, `mac_type`, and `mac_scroll`.
  259. - Use screenshots/vision only when Accessibility data is missing or ambiguous.
  260. The extension auto-detects the macOS-MCP checkout. If you use a manually copied extension, set `MACOS_MCP_ROOT=/path/to/MacOS-MCP`.
  261. </details>
  262. <details>
  263. <summary><strong>Other Integrations</strong></summary>
  264. Any client supporting the Model Context Protocol can integrate macOS-MCP by configuring the `uvx macos-mcp serve` command in their MCP server settings.
  265. </details>
  266. ---
  267. ## MCP Tools
  268. macOS-MCP provides a comprehensive toolset for desktop automation:
  269. | Tool | Purpose |
  270. |------|---------|
  271. | **Click** | Click at coordinates with support for left, right, and double-click |
  272. | **Type** | Type text at cursor position, optionally clearing existing text |
  273. | **Scroll** | Scroll vertically or horizontally in focused window or regions |
  274. | **Move** | Move mouse pointer or drag to coordinates |
  275. | **Shortcut** | Press keyboard shortcuts (Cmd+C, Cmd+Tab, etc.) |
  276. | **App** | Launch applications, manage windows (resize/move), switch between apps. Supports app names and bundle IDs |
  277. | **Desktop** | Create a new Mission Control Space (virtual desktop) via Accessibility, verifying the space count increased |
  278. | **Shell** | Execute commands or AppleScript. Use `mode='osascript'` for AppleScript |
  279. | **Scrape** | Extract and convert webpage content to Markdown format |
  280. | **Wait** | Pause execution for a defined duration |
  281. ## Limitations
  282. - **Accessibility Requirements**: Manual permission grant required in System Preferences
  283. - **App Compatibility**: Some applications have limited or no Accessibility API support
  284. - **Performance Variance**: Complex UIs with many elements may have slower traversal
  285. - **Text Input**: Some specialized input fields may not properly receive keystrokes
  286. - **Authentication**: Cannot interact with system authentication dialogs
  287. ## Security & Access Control
  288. ### Authentication
  289. ```shell
  290. macos-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"
  291. ```
  292. Requires `Authorization: Bearer your_token` header on all requests.
  293. ### IP Allowlist
  294. ```shell
  295. macos-mcp serve --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"
  296. ```
  297. Restricts connections to specified CIDR ranges.
  298. ### TLS/HTTPS
  299. ```shell
  300. openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
  301. macos-mcp serve --ssl-certfile cert.pem --ssl-keyfile key.pem
  302. ```
  303. ### OAuth 2.0 + PKCE
  304. For MCP clients that use OAuth (e.g. Claude Desktop) instead of a static API key:
  305. ```shell
  306. macos-mcp serve --transport streamable-http --host 0.0.0.0 \
  307. --ssl-certfile ~/.macos-mcp/cert.pem \
  308. --ssl-keyfile ~/.macos-mcp/key.pem \
  309. --oauth-client-id my-client \
  310. --oauth-client-secret my-secret
  311. ```
  312. **Claude Desktop config** (via `mcp-remote` bridge — see [Integration Options](#integration-options)):
  313. ```json
  314. {
  315. "mcpServers": {
  316. "macos-mcp": {
  317. "command": "npx",
  318. "args": [
  319. "-y",
  320. "mcp-remote",
  321. "https://<host>:8000/mcp",
  322. "--transport",
  323. "http-only"
  324. ]
  325. }
  326. }
  327. }
  328. ```
  329. > **Note:** Claude Desktop's `claude_desktop_config.json` does not support
  330. > `"type": "http"` or `"url"` entries directly. Use `mcp-remote` as shown
  331. > above, or add the server via **Settings → Connectors → Add custom connector**
  332. > in the Claude Desktop UI.
  333. The OAuth server exposes:
  334. - `GET /.well-known/oauth-authorization-server` — server metadata (RFC 8414)
  335. - `GET /oauth/authorize` — Authorization Code + PKCE (`S256` required)
  336. - `POST /oauth/token` — token exchange (client secret required)
  337. - `POST /oauth/register` — disabled; clients must be pre-provisioned
  338. Dynamic client registration is disabled. Redirect URIs must be loopback `http(s)` only.
  339. Auth key and OAuth can coexist — both are accepted as valid Bearer tokens.
  340. ### SSRF Protection
  341. The `Scrape` tool blocks: private IPs, loopback, link-local, credentials-in-URLs, non-HTTP schemes.
  342. ### Config File (`~/.macos-mcp/config.toml`)
  343. Instead of passing flags every time, store your configuration in `~/.macos-mcp/config.toml`. CLI flags always override config file values.
  344. **Search order:**
  345. 1. `--config /path/to/config.toml`
  346. 2. `~/.macos-mcp/config.toml`
  347. **stdio** — local only, no security needed:
  348. ```toml
  349. [server]
  350. transport = "stdio"
  351. ```
  352. **SSE** — network access with auth and IP restriction:
  353. ```toml
  354. [server]
  355. transport = "sse"
  356. host = "0.0.0.0"
  357. port = 8000
  358. auth_key = "your-secret-key"
  359. [security]
  360. ip_allowlist = ["192.168.1.0/24"]
  361. ```
  362. **Streamable HTTP** — network access with auth and TLS (recommended for production):
  363. ```toml
  364. [server]
  365. transport = "streamable-http"
  366. host = "0.0.0.0"
  367. port = 8000
  368. auth_key = "your-secret-key"
  369. ssl_certfile = "cert.pem" # resolved relative to ~/.macos-mcp/
  370. ssl_keyfile = "key.pem"
  371. [security]
  372. ip_allowlist = ["192.168.1.0/24"]
  373. oauth_client_id = "my-client" # optional — enables OAuth 2.0 + PKCE
  374. oauth_client_secret = "my-secret"
  375. [tools]
  376. exclude = ["Shell", "Scrape"] # disable specific tools
  377. ```
  378. Available tool names: `App`, `Shell`, `Snapshot`, `Click`, `Type`, `Scroll`, `Move`, `Shortcut`, `Wait`, `Scrape`, `Notification`
  379. Place your cert and key files in the same directory:
  380. ```
  381. ~/.macos-mcp/
  382. ├── config.toml
  383. ├── cert.pem
  384. └── key.pem
  385. ```
  386. Generate a self-signed cert directly into that directory:
  387. ```shell
  388. mkdir -p ~/.macos-mcp
  389. openssl req -x509 -newkey rsa:4096 \
  390. -keyout ~/.macos-mcp/key.pem \
  391. -out ~/.macos-mcp/cert.pem \
  392. -days 365 -nodes
  393. ```
  394. ---
  395. ## Environment Variables
  396. All variables are optional. Set them via the `env` key in `claude_desktop_config.json`.
  397. | Variable | Default | Description |
  398. |---|---|---|
  399. | `ANONYMIZED_TELEMETRY` | `true` | Set to `false` to disable anonymous usage telemetry. No personal data, tool arguments, or outputs are ever collected. |
  400. | `MACOS_MCP_AUTH_KEY` | _(none)_ | Bearer token required on all HTTP requests. Alternative to `--auth-key` CLI flag. |
  401. | `MACOS_MCP_IP_ALLOWLIST` | _(none)_ | Comma-separated list of allowed client IPs or CIDR ranges. Alternative to `--ip-allowlist` CLI flag. |
  402. | `MACOS_MCP_SSL_CERTFILE` | _(none)_ | Path to TLS certificate file (.pem). Must be provided with `MACOS_MCP_SSL_KEYFILE`. |
  403. | `MACOS_MCP_SSL_KEYFILE` | _(none)_ | Path to TLS private key file (.pem). Must be provided with `MACOS_MCP_SSL_CERTFILE`. |
  404. **Example `claude_desktop_config.json` (remote with auth + TLS):**
  405. ```json
  406. {
  407. "mcpServers": {
  408. "macos-mcp": {
  409. "command": "uvx",
  410. "args": ["macos-mcp", "serve", "--transport", "sse", "--host", "0.0.0.0"],
  411. "env": {
  412. "MACOS_MCP_AUTH_KEY": "your_token",
  413. "MACOS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
  414. "MACOS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
  415. "MACOS_MCP_SSL_KEYFILE": "/path/to/key.pem"
  416. }
  417. }
  418. }
  419. }
  420. ```
  421. ---
  422. ## Telemetry
  423. macOS-MCP collects anonymous usage data to help improve the server. No personal information, tool arguments, or outputs are tracked.
  424. To disable telemetry, set `ANONYMIZED_TELEMETRY` to `false`:
  425. ```json
  426. {
  427. "mcpServers": {
  428. "macos-mcp": {
  429. "command": "uvx",
  430. "args": ["macos-mcp", "serve"],
  431. "env": { "ANONYMIZED_TELEMETRY": "false" }
  432. }
  433. }
  434. }
  435. ```
  436. ---
  437. ## Security
  438. ⚠️ **Important Security Notice**: macOS-MCP operates with full Accessibility API permissions and executes real system operations without sandboxing. It can perform permanent, irreversible actions.
  439. **Before using macOS-MCP:**
  440. - ✅ Grant Accessibility permissions only to trusted applications
  441. - ✅ Understand that Shell commands execute with full user privileges
  442. - ✅ Review AI-generated action plans before execution
  443. - ✅ Use only in virtual machines or isolated environments with valueless data
  444. - ✅ Create backups before testing in production-like scenarios
  445. **⛔ Do NOT use on:**
  446. - Systems with irreplaceable data
  447. - Production machines or shared systems
  448. - Compliance-regulated environments (HIPAA, PCI, etc.)
  449. For detailed security guidance, see [SECURITY.md](SECURITY.md).
  450. ## Contributing
  451. We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
  452. - Development setup and code standards
  453. - Testing requirements
  454. - Pull request process
  455. - Coding conventions (Ruff formatting, 100 char line length)
  456. ## License
  457. macOS-MCP is licensed under the MIT License - see [LICENSE](LICENSE) for details.
  458. ## Acknowledgements
  459. macOS-MCP is built with excellent open-source projects:
  460. - [PyObjC](https://pyobjc.readthedocs.io/) - Python to Objective-C bridge
  461. - [Pillow](https://pillow.readthedocs.io/) - Python Imaging Library
  462. - [FastMCP](https://github.com/jlowin/fastmcp) - MCP framework
  463. - macOS Accessibility API (ApplicationServices)
  464. ## Citation
  465. If you use macOS-MCP in your research or project, please cite:
  466. ```bibtex
  467. @software{macos-mcp,
  468. author = {Jeomon George},
  469. title = {macOS-MCP: Lightweight MCP Server for macOS Automation},
  470. year = {2025},
  471. publisher = {GitHub},
  472. url = {https://github.com/Jeomon/macos-mcp}
  473. }
  474. ```
  475. ---
  476. **Questions or Issues?** [Open an issue](https://github.com/Jeomon/macos-mcp/issues) or check [SECURITY.md](SECURITY.md) for security concerns.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.