AppleScript Automation MCP

A local MCP server that exposes macOS automation actions (AppleScript + a few CLIs) as tools, so any MCP client running on your Mac (Claude Desktop, Cursor, etc.) can drive them.

It runs locally over stdio — osascript needs the real machine, so this can't be a remote/hosted server. Non-destructive only: no delete/erase/shutdown/trash.

Quickstart

macOS, Python 3.10+. Clone and run the installer — it sets up a venv and wires the server into Claude Desktop for you:

git clone https://github.com/anmolol117/applescript-automation-mcp.git
cd applescript-automation-mcp
bash install.sh

Then quit Claude Desktop completely (Cmd-Q) and reopen it. That's it — the rest of this README is for manual setup, HTTP mode, and permissions.

install.sh backs up your existing claude_desktop_config.json (to .bak) and merges in the applescript server without touching other servers.

Install (manual)

pip install -r requirements.txt        # or: pip install "mcp>=1.2.0"
python server.py                       # sanity check; Ctrl-C to stop

Python 3.10+.

Connect a client

Claude Desktop (local). Install into a venv, then point the config at that venv's Python (Claude Desktop launches with a minimal environment, so bare python3 usually won't find mcp):

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Edit ~/Library/Application Support/Claude/claude_desktop_config.json with absolute paths for both the interpreter and the script:

{
  "mcpServers": {
    "applescript": {
      "command": "/ABSOLUTE/PATH/applescript-automation-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/applescript-automation-mcp/server.py"]
    }
  }
}

Quit Claude Desktop completely and reopen it. Connection status and logs live under Settings → Developer. Restart after any config edit.

Other MCP clients (Cursor, etc.) take the same command/args shape.

Run as an HTTP URL

The same file can serve over HTTP instead of stdio, for URL-based clients:

MCP_TRANSPORT=streamable-http python3 server.py
# serves at http://127.0.0.1:8000/mcp

Override MCP_HOST / MCP_PORT if needed. This still runs on your Mac — it's a local URL, not a hosted one.

Using with Claude connectors — read this first

Claude custom connectors expect a public HTTPS MCP endpoint. This server controls your Mac via osascript, so it can only ever run on your Mac — a hosted connector on Anthropic's servers would have no Mac to control and every tool would fail. There is no way to make this a normal hosted connector.

Two real options:

1. Local client (recommended). Use the stdio config above with a client that runs on your Mac (Claude Desktop, Cursor). No URL, no tunnel, nothing exposed to the internet.
2. Tunnel the local HTTP server (advanced, risky). Run the HTTP mode and expose it with a tunnel (e.g. cloudflared tunnel --url http://localhost:8000 or ngrok http 8000), then give Claude the public …/mcp URL. This works only while your Mac and the tunnel stay up, and it exposes full control of your Mac to a public URL — anyone who reaches it can run these tools. Only do this behind authentication you add yourself, and never leave it running.

Push to GitHub

git init && git add . && git commit -m "AppleScript automation MCP server"
git branch -M main
git remote add origin https://github.com/anmolol117/applescript-automation-mcp.git
git push -u origin main

The repo is the source; users clone it and connect via stdio (option 1). A GitHub URL is not itself an MCP endpoint.

Permissions (required)

The first time a tool controls an app, macOS prompts for permission. Approve them, or pre-grant under System Settings → Privacy & Security:

• Automation — the client app (or the terminal launching the server) must be allowed to control Messages, Music, Photos, Contacts, System Events, etc.
• Accessibility — needed by tools that send keystrokes (search_photos, search_music_track).
• Screen Recording — needed for screenshot.

If a tool returns a permission error, it's one of these grants.

Tools

Actions: run_applescript, open_app, close_app, set_volume, mute, unmute, toggle_dark_mode, lock_screen, set_clipboard, notify, say, open_url, search_google, search_youtube, screenshot, compose_mail, send_imessage, facetime_call, create_reminder, maps_directions, search_photos, music_playpause, music_next, music_previous, search_music_track, run_shortcut.

Read-only: frontmost_app, list_running_apps, get_volume, is_muted, battery_status, get_ip, get_datetime, disk_usage, memory_stats, get_clipboard, lookup_contact, now_playing, list_shortcuts.

Notes

• run_applescript refuses destructive scripts (delete/erase/shutdown/etc.).
• run_shortcut is the escape hatch: build anything in the Shortcuts app — Focus modes, HomeKit, timers — and call it by name. Input passing isn't wired up; add -i <file> in run_shortcut if a shortcut needs input.
• send_imessage uses the classic service type = iMessage selector, which can break on some macOS versions if no iMessage account is active; check Messages is signed in if it errors.
• Every tool returns {ok, output, error} and never hangs — subprocess calls time out instead of blocking the client.