steipete/macos-automator-mcp

execute_script

Automate macOS tasks using AppleScript or JXA (JavaScript for Automation) to control applications like Terminal, Chrome, Safari, Finder, etc.

1. Script Source (Choose one):

• kb_script_id (string): Preferred. Executes a pre-defined script from the knowledge base by its ID. Use get_scripting_tips to find IDs and inputs. Supports placeholder substitution via input_data or arguments. Ex: kb_script_id: "safari_get_front_tab_url".
• script_content (string): Executes raw AppleScript/JXA code. Good for simple or dynamic scripts. Ex: script_content: "tell application \"Finder\" to empty trash".
• script_path (string): Executes a script from an absolute POSIX path on the server. Ex: /Users/user/myscripts/myscript.applescript.

2. Script Inputs (Optional):

• input_data (JSON object): For kb_script_id, provides named inputs (e.g., --MCP_INPUT:keyName). Values (string, number, boolean, simple array/object) are auto-converted. Ex: input_data: { "folder_name": "New Docs" }.
• arguments (array of strings): For script_path (passes to on run argv / run(argv)). For kb_script_id, used for positional args (e.g., --MCP_ARG_1).

3. Execution Options (Optional):

• language ('applescript' | 'javascript'): Specify for script_content/script_path (default: 'applescript'). Inferred for kb_script_id.
• timeout_seconds (integer, optional, default: 60): Sets the maximum time (in seconds) the script is allowed to run. Increase for potentially long-running operations.
• output_format_mode (enum, optional, default: 'auto'): Controls osascript output formatting.
  • 'auto': Smart default - resolves to 'human_readable' for AppleScript and 'direct' for JXA.
  • 'human_readable': For AppleScript, uses -s h flag.
  • 'structured_error': For AppleScript, uses -s s flag (structured errors).
  • 'structured_output_and_error': For AppleScript, uses -s ss flag (structured output & errors).
  • 'direct': No special output flags (recommended for JXA).
• include_executed_script_in_output (boolean, optional, default: false): If true, the final script content (after any placeholder substitutions) or script path that was executed will be included in the response. This is useful for debugging and understanding exactly what was run. Defaults to false.
• include_substitution_logs (boolean, default: false): For kb_script_id, includes detailed placeholder substitution logs.
• report_execution_time (boolean, optional, default: false): If true, an additional message with the formatted script execution time will be included in the response. Defaults to false.

get_scripting_tips

Discover how to automate any app on your Mac with this comprehensive knowledge base of AppleScript/JXA tips and runnable scripts. This tool is essential for discovery and should be the FIRST CHOICE when aiming to automate macOS tasks, especially those involving common applications or system functions, before attempting to write scripts from scratch. It helps identify pre-built, tested solutions, effectively teaching you how to control virtually any aspect of your macOS experience.

Primary Use Cases & Parameters:

• Discovering Solutions (Use search_term):

  • Parameter: search_term (string, optional).
  • Functionality: Performs a fuzzy search across all tip titles, descriptions, keywords, script content, and IDs. Ideal for natural language queries like "how to..." (e.g., search_term: "how do I get the current Safari URL and title?"). This is the most common way to find relevant tips.
  • Output: Returns a list of matching tips in Markdown format.

• Limiting Search Results (Use limit):

  • Parameter: limit (integer, optional, default: 10).
  • Functionality: Specifies the maximum number of script tips to return when using search_term or browsing a specific category (without list_categories: true). Does not apply if list_categories is true.

• Browsing by Category (Use category):

  • Parameter: category (string, optional).
  • Functionality: Shows tips from a specific category. Combine with limit to control result count.
  • Example: category: "01_intro" or category: "07_browsers/chrome".

• Listing All Categories (Use list_categories: true):

  • Parameter: list_categories (boolean, optional).
  • Functionality: Returns a structured list of all available categories with their descriptions. This helps you understand what automation areas are covered.
  • Output: Category tree in Markdown format.

• Refreshing Database (Use refresh_database: true):

  • Parameter: refresh_database (boolean, optional).
  • Functionality: Forces a reload of the knowledge base if new scripts have been added. Typically not needed as the database refreshes automatically.

Best Practices:

1. Always start with search: Use natural language queries to find solutions (e.g., "send email from Mail app").
2. Browse categories when exploring: Use list_categories: true to see available automation areas.
3. Use specific IDs for execution: Once you find a script, use its ID with execute_script tool for precise execution.