MacOS Automator

An MCP server that transforms your AI assistant into a powerful macOS automation tool. Execute AppleScript and JavaScript for Automation (JXA) scripts to control any macOS application programmatically.

Features

• Execute Scripts: Run AppleScript or JXA scripts inline, from files, or from a built-in knowledge base of 200+ pre-built automation recipes
• Knowledge Base: Search and discover automation scripts across categories like Finder, Safari, Terminal, System Settings, and more
• Accessibility Query: Inspect and interact with UI elements using the macOS accessibility framework - click buttons, read text, and navigate application interfaces programmatically
• Application Control: Automate Safari, Chrome, Mail, Calendar, Music, Terminal, and any scriptable macOS application
• File System Operations: Create folders, read/write files, manage the clipboard, and organize your digital workspace
• System Interactions: Toggle dark mode, display notifications, control volume, and manipulate system settings

Tools

execute_script

Execute AppleScript or JXA scripts with multiple input methods:

• Inline script content
• File path to a script
• Knowledge base script ID (from 200+ pre-built recipes)

Supports passing arguments and structured input data, configurable timeouts, and various output formatting modes. Use include_executed_script_in_output and include_substitution_logs for debugging.

get_scripting_tips

Your automation encyclopedia! Search through 200+ pre-built scripts by category or keyword. Perfect for discovering what's possible:

• List all available categories
• Filter by category (finder, safari, terminal, etc.)
• Search for specific automation tasks
• Refresh the database to load latest scripts

accessibility_query

Powered by the ax binary, this tool provides X-ray vision for macOS UI elements:

• Query UI elements by role, attributes, and navigation path
• Perform actions like clicking buttons programmatically
• Inspect element properties and hierarchy
• Support for both single element queries and returning all matches
• Multiple output formats: smart (readable), verbose (detailed), or text_content (compact)

Requirements

⚠️ CRITICAL: macOS Permissions Required

The application running this MCP server needs explicit permissions:

1. Automation Permissions: Go to System Settings > Privacy & Security > Automation, find the application running the server (e.g., Terminal), and enable checkboxes for applications it needs to control.

2. Accessibility Permissions: For UI scripting and the accessibility_query tool, go to System Settings > Privacy & Security > Accessibility and add/enable the application running the server.

Optional Configuration

• LOG_LEVEL: Set to DEBUG, INFO, WARN, or ERROR to control logging verbosity
• KB_PARSING: Set to 'lazy' (default, faster startup) or 'eager' (load all scripts at startup)
• LOCAL_KB_PATH: Custom path for local knowledge base (default: ~/.macos-automator/knowledge_base)

Examples

Get Safari's current URL:

{"kb_script_id": "safari_get_front_tab_url"}```

**Toggle dark mode:**
```json
{"kb_script_id": "systemsettings_toggle_dark_mode_ui"}```

**Create a folder on Desktop:**
```json
{"kb_script_id": "finder_create_new_folder_desktop", "input_data": {"folder_name": "My Folder"}}```

**Find and click a button:**
```json
{"command": "perform", "locator": {"app": "Safari", "role": "AXButton", "match": {"AXTitle": "Settings"}}, "action_to_perform": "AXPress"}```