szoloth/macos-automator

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

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