macOS Automator

Overview

This skill enables control of macOS through AppleScript and JavaScript for Automation (JXA). It provides access to 200+ pre-built automation scripts and the ability to execute custom scripts or interact with UI elements via accessibility APIs.

Available Tools

The macOS Automator MCP provides three tools:

1. `mcp__macos_automator__execute_script`

Execute AppleScript or JXA scripts. Supports three input modes:

Parameter	Description
`script_content`	Inline script code
`script_path`	Path to a script file
`kb_script_id`	ID of a knowledge base script
`language`	`applescript` (default) or `javascript`
`args`	Arguments to pass to the script
`timeout_seconds`	Execution timeout (default: 60)

2. `mcp__macos_automator__get_scripting_tips`

Search the knowledge base of 200+ pre-built scripts:

Parameter	Description
`search_term`	Keyword to search for
`category`	Filter by category
`list_categories`	Set `true` to list all categories

3. `mcp__macos_automator__accessibility_query`

Query and interact with UI elements via accessibility APIs:

Parameter	Description
`command`	`query`, `click`, `get_value`, etc.
`locator`	Object with `app`, `role`, `match` properties
`return_all_matches`	Return all matching elements

Quick Start Patterns

Using Knowledge Base Scripts

To find available scripts for a task:

1. Call get_scripting_tips with search_term or list_categories=true
2. Find the relevant kb_script_id
3. Call execute_script with that kb_script_id

Common Knowledge Base Script Categories

safari - Browser automation (tabs, URLs, bookmarks)
finder - File operations
mail - Email automation
spotify / music - Media control
system - System settings, notifications
clipboard - Clipboard operations
terminal - Terminal automation

Custom AppleScript

For tasks without a KB script, write inline AppleScript:

{
  "script_content": "tell application \"Finder\" to get name of every item of desktop",
  "language": "applescript"
}

UI Automation via Accessibility

For apps with limited AppleScript support, use accessibility queries:

{
  "command": "query",
  "locator": {
    "app": "System Settings",
    "role": "AXButton",
    "match": {"AXTitle": "General"}
  }
}

Common Tasks

Get Current Browser Tab URL

{"kb_script_id": "safari_get_active_tab_url"}

List Running Applications

tell application "System Events" to get name of every process whose background only is false

Get Clipboard Contents

the clipboard

Control Spotify

{"kb_script_id": "spotify_play_pause"}
{"kb_script_id": "spotify_next_track"}
{"kb_script_id": "spotify_get_current_track"}

Send Notification

display notification "Message here" with title "Title"

Get Frontmost Application

tell application "System Events" to get name of first process whose frontmost is true

Take Screenshot

do shell script "screencapture -x ~/Desktop/screenshot.png"

Troubleshooting

Permission Errors

The terminal app running Claude Code needs permissions in System Settings > Privacy & Security:

Automation: To control other applications
Accessibility: For UI scripting

Script Timeout

Increase timeout_seconds for long-running operations (default is 60s, max 600s).

Script Syntax Errors

Test scripts in Script Editor.app first to validate syntax before using with the MCP.

Workflow: Discovering and Using Scripts

Search first: Call get_scripting_tips with a search term related to the task
Review results: Check if a pre-built script exists
Execute: Use kb_script_id if available, or write custom script
Handle errors: Check for permission issues if script fails

macos-automator