Provides tools for controlling various Apple ecosystem apps and macOS system functions, including Finder, Calendar, Reminders, Notes, Mail, Contacts, Photos, and more via AppleScript.
Allows control of Apple Music playback, playlists, search, and library management.
Enables sending and reading iMessages, as well as managing conversations.
Exposes macOS system controls such as volume, brightness, display settings, network, bluetooth, screenshots, keyboard input, text-to-speech, and system actions like sleep and lock.
Provides tools for browsing, opening URLs, managing tabs, and executing JavaScript in Safari.
Allows control of Spotify playback, playlists, search, and volume.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Apple MCP Server show me the current song playing"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: applescript-mcp
git clone https://github.com/lacausecrypto/apple-mcp-server.git
cd apple-mcp-server
npm install
npm run buildRegister in your MCP config (~/.claude/.mcp.json or project .mcp.json):
{
"mcpServers": {
"apple": {
"command": "node",
"args": ["/absolute/path/to/apple-mcp-server/dist/index.js"]
}
}
}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)"Actions are classified into three levels. Conservative by default — destructive actions require explicit confirmation.
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"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.
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.
Override defaults via ~/.config/apple-mcp/permissions.json:
{
"blocked": ["empty_trash"],
"unprotected": ["like", "send"],
"unblocked": ["restart"],
"protected": ["play", "pause"]
}Key | Effect |
| Add actions to BLOCKED (on top of defaults) |
| Move from PROTECTED → OPEN (skip confirmation) |
| Move from BLOCKED → PROTECTED (allow with confirmation) |
| Move from OPEN → PROTECTED (add confirmation) |
Actions can be specified as "actionName" (global) or "apple_tool.actionName" (specific).
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:
{ "rate_limit": { "global_per_min": 60, "protected_per_min": 10 } }Preview every action without executing. Useful for testing what Claude would do:
{ "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.
Every tool call is logged as a structured JSON line in ~/.local/occ/rag/apple-mcp-audit.jsonl:
{"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:
# 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)})'Tool | # | Actions | Protected/Blocked |
| 7 |
| — |
| 2 |
| — |
| 3 |
| — |
| 7 |
|
|
| 19 |
| — |
| 26 |
|
|
| 17 |
| — |
| 17 |
| — |
| 14 |
| — |
| 10 |
|
|
| 8 |
|
|
| 10 |
|
|
| 9 |
|
|
| 20 |
|
|
| 14 |
| — |
| 30 |
|
|
| 5 |
| — |
| 1 |
| — |
| 8 |
| — |
| 3 |
| — |
| 11 |
|
|
| 2 |
| — |
| 2 |
| — |
| 9 |
|
|
| 10 |
| — |
| 5 |
|
|
| 7 |
| — |
| 5 |
| — |
| 11 |
| — |
| 4 |
| — |
| 7 |
| — |
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 |
| Allowlist: only permits paths under |
| Escapes |
| Escapes quotes, strips |
| 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.
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.
URI | Description |
| Current track from Apple Music or Spotify |
| Battery, disk, uptime, CPU load, RAM |
| All open Safari tabs |
| All open Chrome tabs |
Create src/domains/myapp.ts (see existing domains for pattern)
Import and register in src/registry.ts
If destructive, add to DEFAULT_PROTECTED in src/permissions.ts
npm run build && npm test
npm run build
npm test # 135 tests (executor + registry + permissions)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.
~/.local/occ/rag/apple-mcp.log
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 testsMIT
Manage macOS applications. Actions: open, quit, force_quit, is_running, list_running, hide, activate.
Inputs: action (required), name, confirm.
Control Apple Books. Actions: library, reading_now, collections, search, open. Note: Books has limited AppleScript support — some actions may return partial results.
Inputs: action (required), query, confirm.
Control macOS display brightness. Actions: up, down.
Inputs: action (required), confirm.
Control Apple Calendar. Actions: list, today, tomorrow, create_event, delete_event, week, date_events, modify_event.
Inputs: action (required), date, hour, title, +3 more.
Control Google Chrome browser. Actions: 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.
Inputs: action (required), url, code, confirm.
Read and write the macOS clipboard. Actions: get, set, clear.
Inputs: action (required), text, confirm.
Control Apple Contacts. Actions: search, get, list, create, groups, group_members, delete, update_phone, update_email.
Inputs: action (required), name, email, phone, +4 more.
Make FaceTime calls. Actions: call (video), audio.
Inputs: action (required), confirm, contact.
Manage Finder: files, folders, trash, wallpaper, disks, tags. Actions: open_folder, reveal, desktop_files, empty_trash, trash_count, eject_disk, eject_all, set_wallpaper, create_folder, file_info, rename, move, copy, delete, create_alias, get_selection, tags, set_tag, list_folder, disk_info.
Inputs: action (required), tag, name, path, +4 more.
Control Pages, Numbers, and Keynote. Actions: 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.
Inputs: action (required), path, confirm.
Simulate keyboard input. Actions: type_text, press_key, copy, paste, undo, redo, save, select_all.
Inputs: action (required), text, combo, confirm.
Control Apple Mail. Actions: unread_count, check, unread_list, send, mark_all_read, read_body, search, draft, mailboxes, move_to_trash.
Inputs: action (required), to, body, query, +3 more.
Open Apple Maps with a search query or directions. Actions: open, directions.
Inputs: action (required), to, from, query, +1 more.
Control Apple Messages / iMessage. Actions: recent, send, unread, conversation, search.
Inputs: action (required), to, text, limit, +3 more.
Control Apple Music. Actions: 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, remove_from_playlist, create_playlist, delete_playlist, get_lyrics, radio.
Inputs: action (required), name, level, query, +3 more.
Control Apple Notes. Actions: list, create, read, search, delete, folders, move, append, count.
Inputs: action (required), body, text, query, +3 more.
Send macOS notifications. Actions: send.
Inputs: action (required), sound, title, confirm, +1 more.
Control Apple Photos. Actions: albums, recent, search, favorites, album_contents, export, count, create_album, add_to_album, import.
Inputs: action (required), name, path, album, +3 more.
Control Apple Podcasts. Actions: now_playing, play, pause, next, shows, episodes, search.
Inputs: action (required), name, query, confirm.
Control Preview app. Actions: open, list_open, close, close_all. Note: Preview has limited AppleScript support.
Inputs: action (required), path, confirm.
Control Apple Reminders. Actions: list_lists, list, add, complete, delete, set_due, set_priority, add_note, overdue, create_list.
Inputs: action (required), name, text, confirm, +4 more.
Control Safari browser. Actions: 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.
Inputs: action (required), url, code, confirm.
Take screenshots on macOS. Actions: full, clipboard, timed, area, window.
Inputs: action (required), path, confirm, seconds.
Control Spotify. Actions: 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.
Inputs: action (required), uri, name, level, +2 more.
Read macOS system information. Actions: 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.
Inputs: action (required), confirm.
System controls: sleep, restart, shutdown, lock, dark mode, DND, caffeinate, wifi, bluetooth, shortcuts, prefs, audio, screen saver, AirDrop, login items, Time Machine, audio devices. Actions: sleep, sleep_display, restart, shutdown, logout, 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, eject_all_disks, time_machine, audio_output, audio_input.
Inputs: action (required), name, pane, confirm, +1 more.
Control TextEdit. Actions: create, open, get_text, set_text, save, close, list_open.
Inputs: action (required), path, text, confirm.
Text-to-speech on macOS. Actions: say, list_voices, stop.
Inputs: action (required), rate, text, voice, +1 more.
Control X/Twitter via Safari. Actions: post, draft, save, list_drafts, post_draft, reply, like, retweet, feed, notifications, dm_check.
Inputs: action (required), num, text, confirm, +2 more.
Control macOS system volume. Actions: get, set, up, down, mute, unmute, info.
Inputs: action (required), level, confirm.
Manage macOS windows: move, resize, minimize, fullscreen. Actions: frontmost_app, minimize, minimize_all, maximize, left_half, right_half, fullscreen, close, hide_app, hide_others, center, resize, list_windows, switch_to.
Inputs: action (required), name, width, height, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 31 tools
Each tool targets a distinct macOS domain or application (e.g., brightness, Music, Safari, Calendar). Despite some surface-level overlap (e.g., apple_music vs apple_spotify, apple_safari vs apple_chrome), the tool names and action lists clearly separate their purposes, leaving no real ambiguity.
All tool names follow the exact pattern 'apple_<domain>', using lowercase snake_case throughout (e.g., apple_brightness, apple_sysinfo, apple_textedit). This is perfectly consistent and predictable, making it easy for an agent to infer the tool for a given task.
With 31 tools, this server exceeds the 25+ threshold considered 'too many' in the calibration. Even though each tool represents a distinct feature area, the sheer number creates a heavy surface that may overwhelm agents and complicate selection.
The tool set covers a wide range of macOS apps and system functions, including core apps (Mail, Calendar, Notes, Messages), media (Music, Spotify, Podcasts), browsers (Safari, Chrome), and system controls. Minor gaps exist (e.g., no Apple TV, no HomeKit, some apps have limited actions), but these are not critical for common tasks.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Run Apple Search Ads from Claude: performance, recommendations, keywords, budgets, launches.
Agent personas for Claude. 16 tools, 13 personas, 3 workflows. Zero extra API cost. Free.
