# Apple MCP Server

![Tools](https://img.shields.io/badge/tools-31-blue?style=flat-square)
![Actions](https://img.shields.io/badge/actions-303-green?style=flat-square)
![Resources](https://img.shields.io/badge/resources-4-cyan?style=flat-square)
![Tests](https://img.shields.io/badge/tests-135_passing-brightgreen?style=flat-square)
![Platform](https://img.shields.io/badge/platform-macOS-lightgrey?style=flat-square&logo=apple)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-SDK_1.7-8B5CF6?style=flat-square)
![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)

An MCP server that exposes macOS system controls and Apple apps as structured tools for Claude. Built with TypeScript and the official `@modelcontextprotocol/sdk`.

**31 tools, 303 actions, 4 resources.** Each Apple app is a single MCP tool with an `action` parameter.

## Requirements

- macOS (tested on macOS 15 with Apple Silicon)
- Node.js 18+
- Claude CLI or any MCP-compatible client
- Some features require "Allow JavaScript from Apple Events" in Safari > Develop

## Setup

```bash
git clone https://github.com/lacausecrypto/apple-mcp-server.git
cd apple-mcp-server
npm install
npm run build
```

Register in your MCP config (`~/.claude/.mcp.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "apple": {
      "command": "node",
      "args": ["/absolute/path/to/apple-mcp-server/dist/index.js"]
    }
  }
}
```

## How it works

```
Claude calls apple_music with {action: "now_playing"}
  → index.ts checks permissions (OPEN → proceed)
  → dispatches to domains/music.ts handler
  → handler calls runAppleScript() in executor.ts
  → AppleScript written to temp file, executed via osascript
  → result returned to Claude: "Bohemian Rhapsody — Queen (3:21/5min)"
```

## Permission System

Actions are classified into three levels. **Conservative by default** — destructive actions require explicit confirmation.

### OPEN (default)

Read-only and safe actions execute immediately. No confirmation needed.

```
Claude: apple_volume.get → "Volume: 56%"
Claude: apple_music.now_playing → "Bohemian Rhapsody — Queen"
Claude: apple_sysinfo.battery → "95%; charging"
```

### PROTECTED (27 actions)

Destructive or irreversible actions return a preview and require `confirm: true` to execute.

```
Claude: apple_finder.empty_trash
→ "⚠️ apple_finder.empty_trash requires confirmation.
   Reason: Permanently deletes all items in Trash
   To proceed, call again with confirm: true."

Claude: apple_finder.empty_trash with confirm: true
→ "Trash emptied"
```

Protected actions include: file delete/move/rename, send email/iMessage, post/like/reply on Twitter, delete contacts/notes/reminders/events, force quit apps, system sleep.

### BLOCKED (3 actions)

Never executed. Returns an error with instructions to unblock.

```
Claude: apple_system.shutdown
→ "🚫 apple_system.shutdown is blocked.
   Blocked by default (dangerous system action)."
```

Blocked by default: `shutdown`, `restart`, `logout`.

### Configuration

Override defaults via `~/.config/apple-mcp/permissions.json`:

```json
{
  "blocked": ["empty_trash"],
  "unprotected": ["like", "send"],
  "unblocked": ["restart"],
  "protected": ["play", "pause"]
}
```

| Key | Effect |
|-----|--------|
| `blocked` | Add actions to BLOCKED (on top of defaults) |
| `unprotected` | Move from PROTECTED → OPEN (skip confirmation) |
| `unblocked` | Move from BLOCKED → PROTECTED (allow with confirmation) |
| `protected` | Move from OPEN → PROTECTED (add confirmation) |

Actions can be specified as `"actionName"` (global) or `"apple_tool.actionName"` (specific).

### Rate Limiting

Prevents spam and abuse. Two independent sliding-window counters:

- **Global**: max 30 tool calls per minute (all actions)
- **Protected**: max 5 confirmed destructive actions per minute

When exceeded, the call is rejected with a wait time. Configurable:

```json
{ "rate_limit": { "global_per_min": 60, "protected_per_min": 10 } }
```

### Dry-Run Mode

Preview every action without executing. Useful for testing what Claude would do:

```json
{ "dry_run": true }
```

```
Claude: apple_finder.delete(path: "~/old.pdf", confirm: true)
→ "[DRY RUN] Would execute apple_finder.delete (confirmed) — no action taken."
```

All actions return previews. Nothing is executed. The audit log records `dry_run` events.

### Audit Log

Every tool call is logged as a structured JSON line in `~/.local/occ/rag/apple-mcp-audit.jsonl`:

```json
{"ts":"2026-03-31T18:36:49Z","tool":"apple_volume","action":"get","permission":"open","confirmed":false,"dry_run":false,"result":"ok","duration_ms":104,"output":"Volume: 56%"}
{"ts":"2026-03-31T18:36:52Z","tool":"apple_finder","action":"empty_trash","permission":"protected","confirmed":false,"dry_run":false,"result":"protected_no_confirm","duration_ms":0}
```

Queryable with jq:

```bash
# All blocked calls
cat apple-mcp-audit.jsonl | jq 'select(.result=="blocked")'

# Calls per tool
cat apple-mcp-audit.jsonl | jq -s 'group_by(.tool) | map({tool: .[0].tool, count: length})'

# Average duration per tool
cat apple-mcp-audit.jsonl | jq -s 'group_by(.tool) | map({tool: .[0].tool, avg_ms: (map(.duration_ms) | add / length)})'
```

## Tools

| Tool | # | Actions | Protected/Blocked |
|------|---|---------|-------------------|
| `apple_volume` | 7 | `get` `set` `up` `down` `mute` `unmute` `info` | — |
| `apple_brightness` | 2 | `up` `down` | — |
| `apple_clipboard` | 3 | `get` `set` `clear` | — |
| `apple_apps` | 7 | `open` `quit` `is_running` `list_running` `hide` `activate` `force_quit` | `force_quit` |
| `apple_sysinfo` | 19 | `battery` `disk` `uptime` `ip` `macos_version` `cpu` `memory` `top_processes` `hostname` `resolution` `summary` `bluetooth_devices` `audio_devices` `printers` `displays` `usb_devices` `network_interfaces` `serial_number` `model` | — |
| `apple_music` | 26 | `play` `pause` `stop` `next` `prev` `restart` `now_playing` `shuffle_on` `shuffle_off` `repeat_off` `repeat_one` `repeat_all` `play_playlist` `list_playlists` `set_volume` `love` `dislike` `search` `play_song` `queue_next` `add_to_playlist` `create_playlist` `get_lyrics` `radio` `remove_from_playlist` `delete_playlist` | `delete_playlist` `remove_from_playlist` |
| `apple_spotify` | 17 | `play` `pause` `next` `prev` `now_playing` `set_volume` `shuffle` `playpause` `play_playlist` `list_playlists` `like` `repeat_off` `repeat_on` `search` `play_track` `current_album` `current_artist` | — |
| `apple_safari` | 17 | `open_url` `current_url` `current_title` `list_tabs` `close_tab` `new_tab` `reload` `page_text` `reading_list` `js_execute` `back` `forward` `bookmarks` `history_recent` `private_window` `close_window` `tab_count` | — |
| `apple_chrome` | 14 | `open_url` `current_url` `current_title` `list_tabs` `close_tab` `reload` `js_execute` `back` `forward` `new_window` `new_incognito` `close_window` `tab_count` `new_tab` | — |
| `apple_mail` | 10 | `unread_count` `check` `unread_list` `read_body` `search` `draft` `mailboxes` `send` `mark_all_read` `move_to_trash` | `send` `mark_all_read` `move_to_trash` |
| `apple_calendar` | 8 | `list` `today` `tomorrow` `create_event` `week` `date_events` `delete_event` `modify_event` | `delete_event` `modify_event` |
| `apple_reminders` | 10 | `list_lists` `list` `add` `complete` `set_due` `set_priority` `add_note` `overdue` `create_list` `delete` | `delete` |
| `apple_notes` | 9 | `list` `create` `read` `search` `folders` `move` `append` `count` `delete` | `delete` |
| `apple_finder` | 20 | `open_folder` `reveal` `desktop_files` `trash_count` `create_folder` `file_info` `copy` `get_selection` `tags` `set_tag` `list_folder` `disk_info` `empty_trash` `delete` `move` `rename` `eject_disk` `eject_all` `set_wallpaper` `create_alias` | `empty_trash` `delete` `move` `rename` `eject_disk` `eject_all` `set_wallpaper` |
| `apple_windows` | 14 | `frontmost_app` `minimize` `minimize_all` `maximize` `left_half` `right_half` `fullscreen` `close` `hide_app` `hide_others` `center` `resize` `list_windows` `switch_to` | — |
| `apple_system` | 30 | `sleep_display` `lock` `dark_mode` `dnd_on` `dnd_off` `caffeinate` `decaffeinate` `wifi_status` `wifi_on` `wifi_off` `wifi_network` `bluetooth_on` `bluetooth_off` `run_shortcut` `list_shortcuts` `open_prefs` `display_settings` `sound_settings` `network_settings` `airdrop` `screen_saver` `login_items` `time_machine` `audio_output` `audio_input` `sleep` `eject_all_disks` `shutdown` `restart` `logout` | `sleep` `eject_all_disks` · Blocked: `shutdown` `restart` `logout` |
| `apple_screenshot` | 5 | `full` `clipboard` `timed` `area` `window` | — |
| `apple_notification` | 1 | `send` | — |
| `apple_keyboard` | 8 | `type_text` `press_key` `copy` `paste` `undo` `redo` `save` `select_all` | — |
| `apple_tts` | 3 | `say` `list_voices` `stop` | — |
| `apple_twitter` | 11 | `draft` `save` `list_drafts` `feed` `notifications` `dm_check` `post` `post_draft` `reply` `like` `retweet` | `post` `post_draft` `reply` `like` `retweet` |
| `apple_facetime` | 2 | `call` `audio` | — |
| `apple_maps` | 2 | `open` `directions` | — |
| `apple_contacts` | 9 | `search` `get` `list` `create` `groups` `group_members` `delete` `update_phone` `update_email` | `delete` `update_phone` `update_email` |
| `apple_photos` | 10 | `albums` `recent` `search` `favorites` `album_contents` `export` `count` `create_album` `add_to_album` `import` | — |
| `apple_messages` | 5 | `recent` `unread` `conversation` `search` `send` | `send` |
| `apple_podcasts` | 7 | `now_playing` `play` `pause` `next` `shows` `episodes` `search` | — |
| `apple_books` | 5 | `library` `reading_now` `collections` `search` `open` | — |
| `apple_iwork` | 11 | `pages_create` `pages_open` `pages_export_pdf` `numbers_create` `numbers_open` `numbers_export_pdf` `keynote_create` `keynote_open` `keynote_export_pdf` `keynote_start_slideshow` `keynote_stop_slideshow` | — |
| `apple_preview` | 4 | `open` `list_open` `close` `close_all` | — |
| `apple_textedit` | 7 | `create` `open` `get_text` `set_text` `save` `close` `list_open` | — |

## Security

### What this provides

**Permission system** — Three-level access control (OPEN/PROTECTED/BLOCKED) enforced before execution. Protected actions require `confirm: true`. Configurable via JSON file.

**Rate limiting** — Sliding-window counters: 30 calls/min global, 5 protected/min. Prevents abuse loops.

**Dry-run mode** — All actions return previews without executing. Safe testing of what Claude would do.

**Structured audit log** — Every call logged as JSON line (tool, action, permission, result, duration). Queryable with jq.

**Input validation** — Not sandboxing. The server validates inputs before passing them to AppleScript or shell:

| Function | What it does |
|----------|-------------|
| `safePath()` | **Allowlist**: only permits paths under `~/`, `/tmp`, `/Volumes/nvme`, `/Applications`. Everything else rejected. |
| `safeAS()` | Escapes `\` and `"` for AppleScript string interpolation. Prevents script injection inside quoted strings. |
| `safeSQL()` | Escapes quotes, strips `;`, `--`, `/* */`, UNION, DDL keywords, hex literals. Used for iMessage sqlite3 queries. |
| `safeAppName()` | Strips shell metacharacters from app names. |

**Concurrency** — `withLock()` serializes Safari and Chrome tab operations to prevent race conditions.

**Execution safety** — AppleScript runs via temp `.scpt` files (not `-e` flag). Shell commands use `execFile` with array arguments (no shell interpolation).

**Auto-launch** — Apps that aren't running are launched automatically on `-600` error and retried once.

**Logging** — All tool calls, permission checks, and errors logged to `~/.local/occ/rag/apple-mcp.log`.

### What this does NOT provide

- **No sandboxing.** The Node process runs with your full user privileges. It can do anything you can do.
- **No network isolation.** The server communicates via stdio (local only), but the actions it executes (email, tweets, etc.) reach the internet.
- **No encryption.** Log files and the permission config are plain text.
- **No authentication on the MCP transport.** Any process that can connect to stdio can call tools.
- **safePath is an allowlist, not a jail.** It prevents operations on system paths, but `~/` is allowed — which includes `~/Library`, `~/.ssh`, etc.

**This is suitable for personal use on your own Mac.** It is not designed for multi-user environments or adversarial contexts.

## Resources

| URI | Description |
|-----|-------------|
| `apple://now-playing` | Current track from Apple Music or Spotify |
| `apple://system-info` | Battery, disk, uptime, CPU load, RAM |
| `apple://open-tabs/safari` | All open Safari tabs |
| `apple://open-tabs/chrome` | All open Chrome tabs |

## Adding a new domain

1. Create `src/domains/myapp.ts` (see existing domains for pattern)
2. Import and register in `src/registry.ts`
3. If destructive, add to `DEFAULT_PROTECTED` in `src/permissions.ts`
4. `npm run build && npm test`

## Testing

```bash
npm run build
npm test    # 135 tests (executor + registry + permissions)
```

## Known limitations

- **Books and Podcasts** have limited AppleScript support. Some actions return generic errors.
- **Spotify** doesn't expose playlists or "like" via AppleScript. Uses URL schemes as fallback.
- **Safari JS execution** requires "Allow JavaScript from Apple Events" in Safari > Develop.
- **Twitter/X** actions depend on the current DOM structure, which may change.
- **safePath** allows all of `~/` — including sensitive directories like `~/.ssh` and `~/Library`.

## Logging

`~/.local/occ/rag/apple-mcp.log`

## Project structure

```
src/
  index.ts          Server entry, permission enforcement, tool dispatch
  permissions.ts    Three-level permission system with config file
  types.ts          Interfaces: ExecResult, DomainModule, DomainAction, ResourceDef
  executor.ts       Execution layer: AppleScript, shell, caching, locking, safety
  registry.ts       Domain registry and JSON Schema builder
  domains/          31 domain files (one per Apple app/category)
  resources/        4 MCP resource providers
tests/
  executor.test.js  Safety function tests
  registry.test.js  Domain registration tests
  permissions.test.js  Permission system tests
```

## License

MIT