macOS Automator MCP Server

Executes AppleScript or JavaScript for Automation (JXA) scripts on macOS. This is the primary tool for performing direct automation actions.

1. Script Source (Exactly one of these MUST be provided):

• kbScriptId (string):
  • Highly Preferred Method. Executes a pre-defined, tested script from the server's knowledge base using its unique ID.
  • Discovery: Use the get_scripting_tips tool to find available scripts, their Runnable IDs (which become this kbScriptId), and any required inputs (see argumentsPrompt from get_scripting_tips).
  • Example: kbScriptId: "safari_get_front_tab_url".
  • Placeholder Substitution: Scripts from the knowledge base can contain placeholders like --MCP_INPUT:keyName or --MCP_ARG_N which will be substituted using the inputData or arguments parameters respectively.
• scriptContent (string):
  • Executes raw AppleScript or JXA code provided directly as a string.
  • Useful for simple, one-off commands or dynamically generated scripts.
  • Example: scriptContent: "tell application \"Finder\" to empty trash".
• scriptPath (string):
  • Executes a script from a local file on the server machine.
  • The path MUST be an absolute POSIX path to the script file (e.g., /Users/user/myscripts/myscript.applescript).
  • Useful for complex or proprietary scripts not in the knowledge base.

2. Providing Inputs to Scripts:

• inputData (JSON object, optional):
  • Primarily for kbScriptId scripts.
  • Used to provide named inputs that replace --MCP_INPUT:keyName placeholders within the knowledge base script.
  • The keys in the object should match the keyName in the placeholders. Values (strings, numbers, booleans, simple arrays/objects) are automatically converted to their AppleScript/JXA literal equivalents.
  • Example: inputData: { "folderName": "New Docs", "targetPath": "~/Desktop" } for a script with --MCP_INPUT:folderName and --MCP_INPUT:targetPath.
• arguments (array of strings, optional):
  • For scriptPath: Passed as an array of string arguments to the script's main handler (e.g., on run argv in AppleScript, run(argv) in JXA).
  • For kbScriptId: Used if a script is specifically designed for positional string arguments (replaces --MCP_ARG_1, --MCP_ARG_2, etc.). Check the script's argumentsPrompt from get_scripting_tips. Less common for KB scripts than inputData.

3. Execution Options:

• language (enum: 'applescript' | 'javascript', optional):
  • Specifies the scripting language.
  • Crucial for scriptContent and scriptPath if not applescript. Defaults to 'applescript' if omitted for these sources.
  • Automatically inferred from the metadata if using kbScriptId.
• timeoutSeconds (integer, optional, default: 30):
  • Sets the maximum time (in seconds) the script is allowed to run before being terminated. Increase for potentially long-running operations.
• useScriptFriendlyOutput (boolean, optional, default: false):
  • If true, uses osascript -ss flag. This can provide more structured output (e.g., proper lists/records) from AppleScript, which might be easier for a program to parse than the default human-readable format.
• includeExecutedScriptInOutput (boolean, optional, default: false):
  • If true, the full script content (after placeholder substitutions for knowledge base scripts) or the scriptPath will be appended to the successful output. Useful for verification and debugging.
• includeSubstitutionLogs (boolean, optional, default: false):
  • Only applies to kbScriptId scripts.
  • If true, detailed logs of each placeholder substitution step performed on the knowledge base script are included in the output (prepended on success, appended on error). Extremely useful for debugging issues with inputData/arguments processing and how they are inserted into the script.

Security Note: Exercise caution, as this tool executes arbitrary code on the macOS machine. Ensure any user-provided script content or files are from trusted sources. macOS permissions (Automation, Accessibility) must be correctly configured for the server process.