macOS (osascript)

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 structuredContent with an outputSchema, 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.

Quick start

Requires macOS 14+ and Node.js 20+.

Claude Code

claude mcp add osx -s user -- npx -y mcp-osx

Claude Desktop

Add 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.

Cursor

Add to ~/.cursor/mcp.json:

{ "mcpServers": { "osx": { "command": "npx", "args": ["-y", "mcp-osx"], "env": { "MCP_OSX_MODE": "compact" } } } }

VS Code (Copilot)

code --add-mcp '{"name":"osx","command":"npx","args":["-y","mcp-osx"]}'

From source

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

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_&lt;name&gt; tool]
  W --> O

Every 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:

1. In the chat, if your client supports elicitation. The tool returns an MCP input_required result 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.
2. 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 properties

The 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

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.

system — 15 actions

settings — 2 actions

app — 5 actions

finder — 5 actions

safari — 6 actions

chromium — 6 actions

spotify — 4 actions

music — 7 actions

tv — 2 actions

vlc — 3 actions

quicktime — 2 actions

photos — 2 actions

keynote — 2 actions

calendar — 4 actions

reminders — 4 actions

notes — 4 actions

contacts — 1 action

mail — 6 actions

lookaway — 1 action

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.

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

~/.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

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 osascript itself. This server only controls access through its own interface.

Troubleshooting

Development

npm install
npm test          # vitest: safety, compile, approval, search and server tests (macOS)
npm run docs      # regenerate the tool reference above
npm run build

Releasing: 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