osa-mcp

Give your AI access to every scriptable app on your Mac.

osa-mcp is an MCP server that automatically discovers all scriptable macOS apps (Mail, Calendar, Finder, Music, Notes, Safari, &c.) and serves their scripting dictionaries to your AI. No configuration, no hardcoded app list. Just connect and go.

What you do

npx

claude mcp add my-mac -- npx -y osa-mcp

bunx

claude mcp add my-mac -- bunx osa-mcp

Homebrew

brew install MayCXC/osa-mcp/osa-mcp
claude mcp add my-mac -- osa-mcp

Remote Mac via SSH

If your AI runs on a different machine, connect to your Mac over SSH. Enable Remote Login in System Settings > General > Sharing first.

claude mcp add my-mac -- npx -y osa-mcp --ssh [email protected]

JSON config

All of the above can also be added to your MCP settings file directly:

{
  "mcpServers": {
    "my-mac": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "osa-mcp"]
    }
  }
}

For SSH, add "--ssh", "[email protected]" to the args.

What you get

osa-mcp serves every scriptable app on your Mac through two tools:

• `search` runs JavaScript over the scripting dictionaries of all the apps, which it reads from your Mac on every search, so apps you install, update or remove show up without a restart. Your AI writes an async arrow function over apps, where each app has the commands, classes, record types, value types and enumerations its dictionary defines.
• `execute` runs JXA or AppleScript on your Mac. A string result comes back as it is, and any other value as source text, so lists, records and object references stay whole.

Your AI reads only what its code selects, so osa-mcp stays light in its context however many apps you have. On a Mac with 33 scriptable apps, the two tools take 21 tokens when the client loads tool definitions on demand, as Claude Code does, and about 2,100 when it loads them all up front.

Examples

A search for the Mail commands whose descriptions mention a mailbox:

async () => apps.find(a => a.name === 'Mail').commands
  .filter(c => c.description.toLowerCase().includes('mailbox'))
  .map(c => c.name)

A JXA script for the names of the disks Finder sees:

Application("Finder").disks.name()

Install from source

git clone https://github.com/MayCXC/osa-mcp.git
cd osa-mcp
bun install
claude mcp add my-mac -- bun "$PWD/src/mcp.ts"

Requires Bun.

License

BSD 3-Clause. See LICENSE.