macOS Automator MCP 🤖 - Your Friendly Neighborhood RoboScripter™

🎯 Mission Control: Teaching Robots to Click Buttons Since 2024

Welcome to the automated future where your Mac finally does what you tell it to! This Model Context Protocol (MCP) server transforms your AI assistant into a silicon-based intern who actually knows AppleScript and JavaScript for Automation (JXA).

No more copy-pasting scripts like a caveman - let the robots handle the robot work! Our knowledge base contains over 200 pre-programmed automation sequences, loaded faster than you can say "Hey Siri, why don't you work like this?"

🚀 Why Let Robots Run Your Mac?

• Remote Control Reality: Execute AppleScript/JXA scripts via MCP - it's like having a tiny robot inside your Mac!
• Knowledge Base of Power: 200+ pre-built automation recipes. From "toggle dark mode" to "extract all URLs from Safari" - we've got your robot needs covered.
• App Whisperer: Control any macOS application programmatically. Make Finder dance, Safari sing, and Terminal... well, terminate things.
• AI Workflow Integration: Connect your Mac to the AI revolution. Your LLM can now actually DO things instead of just talking about them!

🔧 Robot Requirements (Prerequisites)

• Node.js (version >=18.0.0) - Because even robots need a runtime
• macOS - Sorry Windows users, this is an Apple-only party 🍎
• ⚠️ CRITICAL: Permission to Automate (Your Mac's Trust Issues):
  • The application running THIS MCP server (e.g., Terminal, your Node.js application) requires explicit user permissions on the macOS machine where the server is running.
  • Automation Permissions: To control other applications (Finder, Safari, Mail, etc.).
    • Go to: System Settings > Privacy & Security > Automation.
    • Find the application running the server (e.g., Terminal) in the list.
    • Ensure it has checkboxes ticked for all applications it needs to control.
    • See example: docs/automation-permissions-example.png (placeholder image).
  • Accessibility Permissions: For UI scripting via "System Events" (e.g., simulating clicks, keystrokes).
    • Go to: System Settings > Privacy & Security > Accessibility.
    • Add the application running the server (e.g., Terminal) to the list and ensure its checkbox is ticked.
  • First-time attempts to control a new application or use accessibility features may still trigger a macOS confirmation prompt, even if pre-authorized. The server itself cannot grant these permissions.

🏃‍♂️ Quick Start: Release the Robots!

The easiest way to deploy your automation army is via npx. No installation needed - just pure robot magic!

Add this to your MCP client's mcp.json and watch the automation begin:

{
  "mcpServers": {
    "macos_automator": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/macos-automator-mcp@latest"
      ]
    }
  }
}

🛠️ Robot Workshop Mode (Local Development)

Want to tinker with the robot's brain? Clone the repo and become a robot surgeon!

1. Clone the repository:

   git clone https://github.com/steipete/macos-automator-mcp.git
   cd macos-automator-mcp
   npm install # Ensure dependencies are installed
   

2. Configure your MCP client: Update your MCP client's configuration to point to the absolute path of the start.sh script within your cloned repository.

   Example mcp.json configuration snippet:

   {
     "mcpServers": {
       "macos_automator_local": {
         "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh",
         "env": {
           "LOG_LEVEL": "DEBUG"
         }
       }
     }
   }
   

   Important: Replace /absolute/path/to/your/cloned/macos-automator-mcp/start.sh with the correct absolute path on your system.

   The start.sh script will automatically use tsx to run the TypeScript source directly if a compiled version is not found, or run the compiled version from dist/ if available. It respects the LOG_LEVEL environment variable.

   Note for Developers: The start.sh script, particularly if modified to remove any pre-existing compiled dist/server.js before execution (e.g., by adding rm -f dist/server.js), is designed to ensure you are always running the latest TypeScript code from the src/ directory via tsx. This is ideal for development to prevent issues with stale builds. For production deployment (e.g., when published to npm), a build process would typically create a definitive dist/server.js which would then be the entry point for the published package.

🤖 Robot Toolbox

1. execute_script - The Script Launcher 9000

Your robot's primary weapon for macOS domination. Feed it AppleScript or JXA, and watch the magic happen! Scripts can be provided as inline content (script_content), an absolute file path (script_path), or by referencing a script from the built-in knowledge base using its unique kb_script_id.

Script Sources (mutually exclusive):

• script_content (string): Raw script code.
• script_path (string): Absolute POSIX path to a script file (e.g., .applescript, .scpt, .js).
• kb_script_id (string): The ID of a pre-defined script from the server's knowledge base. Use the get_scripting_tips tool to discover available script IDs and their functionalities.

Language Specification:

• language (enum: 'applescript' | 'javascript', optional): Specify the language.
  • If using kb_script_id, the language is inferred from the knowledge base script.
  • If using script_content or script_path and language is omitted, it defaults to 'applescript'.

Passing Inputs to Scripts:

• arguments (array of strings, optional):
  • For script_path: Passed as standard arguments to the script's on run argv (AppleScript) or run(argv) (JXA) handler.
  • For kb_script_id: Used if the pre-defined script is designed to accept positional string arguments (e.g., replaces placeholders like --MCP_ARG_1, --MCP_ARG_2). Check the script's argumentsPrompt from get_scripting_tips.
• input_data (JSON object, optional):
  • Primarily for kb_script_id scripts designed to accept named, structured inputs.
  • Values from this object replace placeholders in the script (e.g., --MCP_INPUT:yourKeyName). See argumentsPrompt from get_scripting_tips.
  • Values (strings, numbers, booleans, simple arrays/objects) are converted to their AppleScript literal equivalents.

Other Options:

• timeout_seconds (integer, optional, default: 60): Maximum execution time.
• output_format_mode (enum, optional, default: 'auto'): Controls osascript output formatting flags.
  • 'auto': (Default) Uses human-readable for AppleScript (-s h), and direct output (no -s flags) for JXA.
  • 'human_readable': Forces -s h (human-readable output, mainly for AppleScript).
  • 'structured_error': Forces -s s (structured error reporting, mainly for AppleScript).
  • 'structured_output_and_error': Forces -s ss (structured output for main result and errors, mainly for AppleScript).
  • 'direct': No -s flags are used (recommended for JXA, also the behavior for JXA in auto mode).
• include_executed_script_in_output (boolean, optional, default: false): If true, the output will include the full script content (after any placeholder substitutions for knowledge base scripts) or the script path that was executed. This is appended as an additional text part in the output content array.
• include_substitution_logs (boolean, optional, default: false): If true, detailed logs of placeholder substitutions performed on knowledge base scripts are included in the output. This is useful for debugging how input_data and arguments are processed and inserted into the script. The logs are prepended to the script output on success or appended to the error message on failure.
• report_execution_time (boolean, optional, default: false): If true, an additional message with the formatted script execution time will be included in the response content array.

SECURITY WARNING & MACOS PERMISSIONS: (Same critical warnings as before about arbitrary script execution and macOS Automation/Accessibility permissions).

Examples:

• (Existing examples for inline/file path remain relevant)
• Using Knowledge Base Script by ID:

  {
    "toolName": "execute_script",
    "input": {
      "kb_script_id": "safari_get_active_tab_url",
      "timeout_seconds": 10
    }
  }
  

• Using Knowledge Base Script by ID with input_data:

  {
    "toolName": "execute_script",
    "input": {
      "kb_script_id": "finder_create_folder_at_path",
      "input_data": {
        "folder_name": "New MCP Folder",
        "parent_path": "~/Desktop"
      }
    }
  }
  

Response Format:

The execute_script tool returns a response in the following format:

{
  content: Array<{
    type: 'text';
    text: string;
  }>;
  isError?: boolean;
}

• content: An array of text content items containing the script output
• isError: (boolean, optional) Set to true when the script execution produced an error. This flag is set when:
  • The script output (stdout) starts with "Error" (case-insensitive)
  • This helps clients easily determine if the execution failed without parsing the output text

Example Response (Success):

{
  "content": [{
    "type": "text",
    "text": "Script executed successfully"
  }]
}

Example Response (Error):

{
  "content": [{
    "type": "text",
    "text": "Error: Cannot find application 'Safari'"
  }],
  "isError": true
}

2. get_scripting_tips - The Robot's Encyclopedia

Your personal automation librari

---