mcp-osx
Controls Apple Music playback, retrieves now-playing information, manages playlists and shuffle, and can stream URLs.
Automates Brave through Chromium actions, including opening URLs, listing and switching tabs, reading the current tab, web search, reloading, and back/forward navigation.
Controls macOS system settings and actions, including dark mode, volume and mute, Wi-Fi, clipboard, notifications, speech, screensaver, display sleep, battery status, and system information.
Provides playback control and now-playing information for QuickTime.
Automates Safari by opening URLs, listing and switching tabs, reading the current tab, performing web searches, managing Reading List items, reloading, and navigating back or forward.
Controls Spotify playback, retrieves now-playing information, manages playlists and shuffle, and can stream URLs.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-osx
Let AI agents control your Mac, safely.
An MCP server that drives macOS through osascript. It has 81 ready-made actions across 19 apps, and the agent can write its own AppleScript when those aren't enough. Nothing arbitrary runs until you approve the exact script.
You: Switch to dark mode, open GitHub in Safari, pause Spotify and tell me what's on my calendar today.
Agent: ✓ system_set_dark_mode ✓ safari_open_url ✓ spotify_control ✓ calendar_list_events
You have 3 meetings today: 10:00 Stand-up, 14:30 Design review, 17:00 1:1 with Sam.Highlights
81 named actions across 19 apps: system settings, Finder, Safari, Chrome, Brave, Spotify, Music, TV, VLC, QuickTime, Photos, Keynote, Calendar, Reminders, Notes, Contacts, Mail and more. Named actions only read, play, open or create. They never send, delete or run code, so they run without prompting you.
Any app with a scripting dictionary: the agent reads the app's dictionary (
sdef), writes a script, and you approve the exact script in the chat or in a native macOS dialog.Workflows: an approved script can be saved as a new tool,
workflow_<name>, so you only approve it once.Small context footprint: works with tool search (Claude Code defers its 87 tools automatically). A compact mode cuts the up-front cost to about 1.2k tokens for clients that load every tool.
Typed results: list actions return
structuredContentwith anoutputSchema, not just text.Bundled skills: one teaches agents to write AppleScript that works on the first try, the other gives ready-made routines (focus mode, start of the workday…).
Built on MCP SDK v2: serves both 2025-era and 2026-07-28 protocol clients over stdio.
Related MCP server: MCP AppleScript
Quick start
Requires macOS 14+ and Node.js 20+.
claude mcp add osx -s user -- npx -y mcp-osxAdd to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"osx": { "command": "npx", "args": ["-y", "mcp-osx"], "env": { "MCP_OSX_MODE": "compact" } }
}
}Compact mode is recommended for clients that load every tool definition up front.
Add to ~/.cursor/mcp.json:
{ "mcpServers": { "osx": { "command": "npx", "args": ["-y", "mcp-osx"], "env": { "MCP_OSX_MODE": "compact" } } } }code --add-mcp '{"name":"osx","command":"npx","args":["-y","mcp-osx"]}'git clone https://github.com/zaosoula/mcp-osx && cd mcp-osx
npm install && npm run build
claude mcp add osx -s user -- node "$PWD/dist/index.js"The first time the server controls an app, macOS asks whether your terminal or MCP client may control it. Click OK. See Permissions.
Things you can ask
Ask | What happens |
"Turn on dark mode and set the volume to 30%" |
|
"What tabs do I have open in Brave?" |
|
"Play my favorites on Spotify" |
|
"What's on my plate this week?" | Calendar, Reminders and unread mail, using the |
"Remind me to call the bank tomorrow at 9" |
|
"Draft an email to Sam about Friday" |
|
"Rename every file on my Desktop to lowercase" | No named action covers it, so the agent writes an AppleScript and you approve it |
"Save that as a workflow called tidy_desktop" | The next time, |
How it works
flowchart LR
A[Agent] -->|named action| N[81 safe actions] --> O[osascript]
A -->|anything else| D[get_app_dictionary] --> S[run_applescript]
S --> P{You approve<br/>the exact script?}
P -- yes --> O
P -- no --> X[Denied: nothing runs]
S -. saveAs .-> W[workflow_<name> tool]
W --> OEvery script the server runs is a constant. Inputs from the agent reach it only as argv (on run argv), never inserted into the script text, so a value like "; do shell script "rm -rf ~ stays a plain string.
Approvals
run_applescript, deleting a workflow, and running a workflow whose file was edited all need your approval:
In the chat, if your client supports elicitation. The tool returns an MCP
input_requiredresult showing the full script. The round-trip state is HMAC-signed and tied to a hash of exactly what you saw, so an approval can't be reused for a different script.In a native macOS dialog otherwise. It shows the full, scrollable script. Deny is the default button, and the dialog denies automatically after 120 seconds.
Anything else, such as an error, a timeout or a closed dialog, counts as deny.
Workflows
// run_applescript arguments
{
"script": "on run argv\n tell application \"Safari\" to open location (\"https://github.com/\" & item 1 of argv)\nend run",
"args": ["anthropics"],
"saveAs": "open_github",
"description": "Open a GitHub org or repo",
"params": [{ "name": "path", "required": true }]
}After you approve, workflow_open_github({ path }) is a new tool and runs without asking. The approval prompt warns you that later runs may pass any value for the declared params. Workflows are stored as readable JSON in ~/.mcp-osx/workflows/. Each one holds a SHA-256 hash of the approved script, and if the file is edited the next run asks you again.
Discover any app
list_scriptable_apps → every installed app that ships a scripting dictionary
get_app_dictionary("Music", "track") → compact summary of its commands, classes and propertiesThe summaries are compact: Spotify's 7 KB sdef becomes about 1.2 KB. They also include Apple's standard suites that sdef leaves out, and they parse the Keynote, Pages and Numbers dictionaries.
Tools
Group | What it covers |
| dark mode, volume, mute, Wi-Fi, clipboard, speech, notifications, screensaver, display sleep, battery, system info |
| open any System Settings pane |
| open, activate, quit, list running, frontmost |
| reveal, open folder, selection, front window path, list a folder |
| open URLs, list and switch tabs, current tab, web search, Reading List, reload, back/forward (Chrome and Brave) |
| playback, now playing, playlists, shuffle, stream URLs |
| albums, slideshows, presentation control |
| list, read and search; create events, reminders and notes (never with attendees) |
| accounts, unread count, list/read messages, check mail, draft (never sends) |
| break-reminder control |
Always available: run_applescript, list_scriptable_apps, get_app_dictionary, list_workflows, run_workflow, delete_workflow, and search_actions / run_action in compact mode.
Deliberately missing: anything that sends (Mail, Messages), deletes, empties, erases, runs code (browser JavaScript, Terminal do script, Shortcuts), writes files, or records. The agent can still do these through run_applescript, which asks you first. A test enforces this rule for every named action, and an osacompile test checks that every action script compiles.
Full reference
81 named actions, generated from the source by npm run docs.
Tool | Args | Description |
| — | Return "true" if macOS dark mode is on, else "false". |
|
| Turn macOS dark mode on or off. |
| — | Return the output volume and mute state. Returns tab-separated: volume (0-100), muted (true/false). |
|
| Set output volume (0-100). |
|
| Mute or unmute audio output. |
| — | Return Wi-Fi power state. |
|
| Turn Wi-Fi on or off. Warning: turning it off may cut the agent's own network connection. |
|
| Show a macOS notification. |
| — | Return the clipboard as plain text (truncated to 10000 chars); non-text clipboards are reported, not returned. |
|
| Replace the clipboard contents with the given text. |
|
| Speak text aloud with macOS text-to-speech (waits until done); optional voice name. |
| — | Start the current screen saver. |
| — | Put the display(s) to sleep now (pmset displaysleepnow); the Mac stays awake. |
| — | Return battery charge, power source and charging state (pmset -g batt). |
| — | Return computer name, macOS version, user, CPU, memory and uptime. Returns tab-separated key, value lines (keys: computer, macos, user, cpu, memory_mb, uptime). |
Tool | Args | Description |
|
| Open a System Settings pane (visible window; changes nothing). See settings_list_panes. |
| — | List the pane names accepted by settings_open_pane, one per line. Returns: pane. |
Tool | Args | Description |
|
| Launch (or bring forward) an application by name. |
|
| Bring a running application to the front. |
|
| Quit an application normally (it may ask to save unsaved work). |
| — | List visible running applications, one name per line. Returns: name. |
| — | Return the name of the frontmost application. |
Tool | Args | Description |
|
| Reveal (select) a file or folder in Finder and bring Finder to the front. |
|
| Open a folder in a new Finder window and bring Finder to the front; errors if the path is missing or not a folder. |
| — | Return the POSIX paths of the items selected in Finder, one per line (max 200). |
| — | Return the POSIX path of the folder shown in the frontmost Finder window. |
|
| List visible items in a folder, one per line (default 50, max 200). Read-only. Returns tab-separated: name, kind (folder/package/file). |
Tool | Args | Description |
|
| Open a URL in Safari (new tab in the front window by default). |
| — | Return the current Safari tab. Returns tab-separated: url, title. |
|
| List open Safari tabs, one per line. Returns tab-separated: window, tab (indexes), current ("*" if current tab, else empty), title, url (cut at 300 chars). |
|
| Bring a Safari tab to the front by window and tab index (from safari_list_tabs); returns its title. |
|
| Search the web with Safari's current search provider, in a new tab (launches Safari if needed). |
|
| Add an http(s) URL (optional title) to the Safari Reading List; launches Safari if needed. |
Tool | Args | Description |
|
| Open an http(s) URL in Chrome or Brave (new tab in the front window by default); launches the browser if needed. |
|
| List open Chrome/Brave tabs, one per line. Returns tab-separated: window, tab (indexes), active ("*" if active tab, else empty), title, url (cut at 300 chars). |
|
| Return the active tab of the front Chrome/Brave window. Returns tab-separated: url, title. |
|
| Bring a Chrome/Brave tab to the front by window and tab index (from chromium_list_tabs); returns its title. |
|
| Reload the active tab in the front Chrome/Brave window. |
|
| Go back or forward in the active tab of the front Chrome/Brave window. |
Tool | Args | Description |
|
| Control Spotify playback: play, pause or resume the song, skip to the next or previous track. |
| — | Return the current Spotify track. Returns tab-separated: name, artist, album, state (playing/paused), url (spotify: URI); "stopped" when nothing plays. |
|
| Play a Spotify track, album or playlist by URI. |
| — | Play the favorites playlist configured as spotify.favorites in ~/.mcp-osx/config.json. |
Tool | Args | Description |
|
| Control Apple Music playback: play, pause or resume the song, skip to the next or previous track, stop; returns the player state. play/playpause may launch Music. |
| — | Return the current Music track. Returns tab-separated: name, artist, album, position_s, duration_s (whole seconds), state (playing/paused/…); "stopped" when nothing plays. |
|
| List Music playlists, one per line (default 20, max 200). Returns tab-separated: name, track_count. |
|
| Play a Music playlist by exact name (launches Music if needed). |
|
| Search the Music library and play the first matching track; returns what is playing (launches Music if needed). |
|
| Turn Music shuffle on or off; returns the new setting. |
|
| Set Music's own sound volume (0-100, not the system volume); returns the new level. |
Tool | Args | Description |
|
| Control TV app playback (play, pause, playpause, next, previous, stop); returns the player state. play/playpause may launch TV. |
| — | Return what the TV app is playing. Returns tab-separated: name, show (empty for movies), position_s, duration_s (whole seconds), state; "stopped" when nothing plays. |
Tool | Args | Description |
|
| Control VLC: play (toggles play/pause; may launch VLC), stop, next, previous, mute (toggle), fullscreen (toggle), volume_up/down, step_forward/backward. |
| — | Return the current VLC item. Returns tab-separated: name, position_s, duration_s (seconds), playing (true/false). |
|
| Open a media stream URL (http, https, rtsp, rtmp) in VLC and start playing it; launches VLC if needed. |
Tool | Args | Description |
|
| Control playback of the front QuickTime Player document: play, pause, stop, step_forward, step_backward; returns its name, position and playing state. |
|
| Open an http(s) media URL in QuickTime Player (opens a visible player window). |
Tool | Args | Description |
|
| List Photos albums, one per line (default 20, max 200). Returns tab-separated: name, item_count. |
|
| Control a Photos slideshow: start (needs album; launches Photos, full screen), stop, next, previous, pause, resume. |
Tool | Args | Description |
|
| Control the Keynote slideshow of the front document: start (full screen), stop, next, previous. |
| — | List open Keynote documents, one per line. Returns tab-separated: name, slide_count, modified (true if unsaved changes). |
Tool | Args | Description |
| — | List Calendar calendars, one per line. Returns tab-separated: name, writable (true/false). |
|
| List Calendar events starting in a range (default today to 7 days ahead), sorted by start. Returns tab-separated: start, end (YYYY-MM-DD HH:MM), summary, location, calendar. Recurring events show only their first occurrence. |
|
| Create a Calendar event (no attendees, no invitations sent). Returns tab-separated: summary, start, end, calendar. Example: {"title":"Dentist","start":"2026-11-12T14:30","end":"2026-11-12T15:15","calendar":"Personnel","location":"12 rue X"} |
|
| Bring Calendar to the front and show the given date, optionally in day, week or month view. |
Tool | Args | Description |
| — | List Reminders lists, one per line. Returns tab-separated: account, list. |
|
| List reminders (incomplete only by default), one per line. Returns tab-separated: name, due (YYYY-MM-DD HH:MM or empty), list, completed (true/false). |
|
| Create a reminder (in the default list unless one is given). Returns tab-separated: name, due, list. |
|
| Mark the first incomplete reminder with this exact name in the given list as completed (reversible). |
Tool | Args | Description |
| — | List Notes folders, one per line. Returns tab-separated: account, folder, note_count. |
|
| List notes (optionally in one folder), one per line. Returns tab-separated: name, modified (YYYY-MM-DD HH:MM). |
|
| Return a note's name, modification date, folder and plaintext (truncated to 4000 chars). |
|
| Create a note from a title and plain-text body (in the default folder unless one is given); returns its name. |
Tool | Args | Description |
|
| Search Contacts by name or organization (read-only), one per line. Returns tab-separated: name, emails, phones (comma-separated), organization. |
Tool | Args | Description |
| — | List Mail accounts, one per line (requires Mail running). Returns tab-separated: name, type, enabled (true/false), email_addresses (comma-separated). |
|
| Return the unread count of the unified inbox, or of one account's INBOX (requires Mail running). |
|
| List recent messages in a mailbox (default inbox), one per line (requires Mail running). Returns tab-separated: date (YYYY-MM-DD HH:MM), sender, subject, read_status (read/unread), id (for mail_read_message). |
|
| Return a message's headers and plain-text content (truncated to 4000 chars) by id from mail_list_messages (requires Mail running). |
| — | Ask Mail to check all accounts for new mail (requires Mail running). |
|
| Open a VISIBLE new-message window in Mail prefilled with to/cc/subject/body; does NOT send (the user reviews and sends). |
Tool | Args | Description |
|
| Control LookAway: start/stop it, reset timers, start a (next/long/custom) break, pause, pause temporarily, postpone the break, resume. |
Typed results
List and "current item" actions declare an outputSchema and return structuredContent:
{ "items": [{ "window": "1", "tab": "2", "active": "*", "title": "Docs", "url": "https://…" }],
"notes": ["… 35 more tabs not shown"] }notes holds lines that aren't records, such as truncation notices or "Safari is not running".
Skills
The server publishes two MCP skills. The client loads them only when needed:
applescript-authoring: how to script an app with no named action. It covers reading the dictionary, passing inputs through argv, getting approval and saving a workflow, with a reference of common AppleScript errors and their fixes.macos-routines: focus mode, presentation mode, start of the workday, end of day, and "what's on my plate", built from named actions.
Context size
Every MCP tool definition takes up context.
Mode | Tools listed | Up-front cost | Use with |
| 81 actions + 6 core tools | Names only with tool search, otherwise ~11k tokens | Clients with tool search (Claude Code) |
|
| ~1.2k tokens | Clients that load every tool |
In compact mode, search_actions("pause song") returns the matching actions with their full JSON input and output schemas, and run_action validates the arguments before anything runs.
Using the Claude API with the MCP connector? The API caller decides which tools are deferred, not the server. Defer everything except the core tools:
{
"type": "mcp_toolset",
"mcp_server_name": "osx",
"default_config": { "defer_loading": true },
"configs": { "run_applescript": { "defer_loading": false }, "get_app_dictionary": { "defer_loading": false } }
}Add tool_search_tool_bm25_20251119 to the same request. Tool names are prefixed by app and descriptions use everyday task words, so searches like "spotify" or "calendar event" find the right tools.
Configuration
Variable | Default | Meaning |
|
|
|
| all | Comma-separated groups to expose, e.g. |
|
| Data directory for |
~/.mcp-osx/config.json:
{ "spotify": { "favorites": "spotify:playlist:37i9dQZF1DXcBWIGoYBM5M" } }Spotify's AppleScript interface can't read your library, so spotify_play_favorites plays this URI. To get it, right-click a playlist in Spotify and choose Share › Copy link.
macOS permissions
Permission | When | Where |
Automation | The first time each app is controlled (error | System Settings › Privacy & Security › Automation |
Accessibility | Only for scripts that click UI through System Events (error | System Settings › Privacy & Security › Accessibility |
Calendars / Reminders / Contacts | The first time those apps are read | macOS asks you |
Permissions apply to the host process, i.e. your terminal or MCP client, not to mcp-osx itself.
Security model
Named actions are non-destructive, use constant scripts, and receive input only through argv.
Arbitrary code runs only after you approve that exact script. Approvals fail closed, and chat approvals are cryptographically tied to what you were shown.
The workflow hash catches accidental or out-of-band edits. It does not protect against a malicious agent that can write files, which could edit a workflow and recompute its hash.
More generally, any agent with shell access can run
osascriptitself. This server only controls access through its own interface.
Troubleshooting
Symptom | Fix |
A call hangs for 30 s, then times out | macOS is probably waiting for you to answer an Automation prompt. Look for it, or check System Settings › Privacy & Security › Automation. |
| Allow your terminal or MCP client under Automation |
| Calendar's AppleScript is slow on large calendars (it has up to 2 minutes). Pass |
| Set |
Tools missing in the client | Check |
Development
npm install
npm test # vitest: safety, compile, approval, search and server tests (macOS)
npm run docs # regenerate the tool reference above
npm run buildReleasing: releases are automatic. On every push to main, .github/workflows/release.yml tests on macOS (Node 20, 22 and 24). If conventional commits of type feat, fix or perf landed since the last tag, it then bumps the version with changelogen, updates CHANGELOG.md and server.json, and tags the release. It builds and smoke-tests the package once and publishes that exact artifact to npm through Trusted Publishing (OIDC, with provenance) and to the MCP Registry, then creates the GitHub release. You can also run it manually with a forced patch, minor or major bump. Publishing from a local machine is blocked.
Adding an app: create src/actions/<group>.ts, prefix every action with <group>_, register it in actionGroups (src/actions/index.ts), and run npm test && npm run docs. The tests reject scripts that insert inputs into the script text, use destructive commands, or don't compile.
License
MIT © Zao Soula
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Build and run agents and automations across hundreds of apps using natural language.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Connect AI agents to your own Chrome with scoped access, approvals, and verified task results.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to interact with macOS applications (Finder, Mail, Contacts, Reminders, Notes, Calendar, TextEdit) using AppleScript. Allows AI assistants to perform tasks like searching contacts, managing files, checking email, and creating reminders through natural language.241MIT
- AlicenseAqualityDmaintenanceEnables Large Language Models to automate macOS applications and execute AppleScript commands through natural language. It features built-in security protections including application allowlists and dangerous pattern detection to prevent unauthorized or risky system operations.21MIT
- AlicenseAqualityDmaintenanceEnables AI agents to control macOS desktop apps via screenshots, mouse clicks, keyboard input, accessibility queries, and AppleScript.1112 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to control macOS applications through AppleScript and JavaScript for Automation, including arbitrary script execution and pre-built app command shortcuts. It also supports safe mode, command previews, search, and registry extension via JSON manifests.28MIT