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.

Provides comprehensive access to a curated knowledge base of AppleScript/JXA tips and runnable scripts for macOS automation. 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.

Primary Use Cases & Parameters:

• Discovering Solutions (Use searchTerm):
  • Parameter: searchTerm (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., searchTerm: "how do I get the current Safari URL and title?") or keyword-based searches (e.g., searchTerm: "Finder copy file to new location"). This is the most common way to find relevant tips.
  • Output: Returns a list of matching tips in Markdown format.
• Listing All Categories (Use listCategories):
  • Parameter: listCategories (boolean, optional, default: false).
  • Functionality: If true, this will return a list of all available script categories (e.g., "safari", "finder_operations", "system_interaction") along with their descriptions and the number of tips in each. This overrides all other parameters.
  • Output: A Markdown list of categories.
• Browsing a Specific Category (Use category):
  • Parameter: category (string, optional).
  • Functionality: Retrieves all tips belonging to the specified category ID. Useful if you know the general area of automation you're interested in.
  • Output: All tips within that category, formatted in Markdown.
• Forcing a Knowledge Base Reload (Use refreshDatabase):
  • Parameter: refreshDatabase (boolean, optional, default: false).
  • Functionality: If true, forces the server to reload the entire knowledge base from disk before processing the request. Primarily useful during development if knowledge base files are being actively modified and you need to ensure the latest versions are reflected without a server restart.

Output Details: The tool returns a single Markdown formatted string. Each tip in the output typically includes:

• Title: A human-readable title for the tip.
• Description: A brief explanation of what the script does.
• Language: applescript or javascript.
• Script: The actual code snippet.
• Runnable ID: A unique identifier (e.g., safari_get_front_tab_url). This ID is critical as it can be directly used as the kbScriptId parameter in the execute_script tool for immediate execution.
• Arguments Prompt: If the script is designed to take inputs when run by ID, this field describes what arguments or inputData are expected by execute_script.
• Keywords: Relevant search terms.
• Notes: Additional context or important considerations.

Workflow Example:

1. User asks: "How do I create a new note in the Notes app with a specific title?"
2. Agent calls get_scripting_tips with searchTerm: "create new note in Notes app with title".
3. Agent reviews the output. If a tip like notes_create_new_note_with_title with a Runnable ID and an argumentsPrompt for noteTitle and noteBody is found:
4. Agent then calls execute_script with kbScriptId: "notes_create_new_note_with_title" and appropriate inputData.