Skip to main content
Glama
macos-automator-mcp

macos-automator-mcp

macOS Automator MCP 🤖 — Give your agent a Mac to operate

macOS Automator MCP

CI npm Node.js macOS License

macOS Automator MCP is a Model Context Protocol server that lets MCP clients discover and run AppleScript or JavaScript for Automation (JXA). It is for agents that need to control macOS applications, inspect the system, or reuse scripts from a bundled knowledge base.

Install

You need macOS and Node.js 24 or newer. Add the server to your MCP client's configuration; npx downloads the current npm release when the client starts it.

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

If your client has a separate package field, use @steipete/macos-automator-mcp without @latest.

Related MCP server: macOS Automator MCP Server

Quick start

Restart your MCP client after adding the configuration. First, ask it to call get_scripting_tips with a small search:

{
  "search_term": "Safari front tab URL",
  "limit": 3
}

Then verify script execution with a read-only inline script through execute_script:

{
  "script_content": "return \"Hello from macOS Automator\""
}

The result is Hello from macOS Automator. Calls that control applications or the user interface may prompt for macOS permissions.

Tools

Tool

Purpose

get_scripting_tips

List knowledge-base categories or search for AppleScript and JXA tips.

execute_script

Run one inline script, script file, or knowledge-base script ID.

Use get_scripting_tips before writing a script from scratch. A returned runnable ID can be passed to execute_script as kb_script_id; scripts with placeholders accept named input_data or positional arguments.

execute_script runs with the privileges of the process hosting the MCP server. Only run scripts you trust, and inspect generated scripts before allowing destructive actions. See the tool reference for every input and response option.

Permissions

The application that launches the MCP server—such as Terminal, an editor, or a desktop MCP client—owns its macOS privacy permissions:

  • Grant Automation access when scripts control Finder, Safari, Mail, or another application.

  • Grant Accessibility access when scripts use System Events for clicks, keystrokes, menus, or other UI scripting.

macOS may show a first-use prompt for each target application. The server cannot grant these permissions itself. See configuration and permissions for setup and common error codes.

Knowledge base

The package includes hundreds of AppleScript and JXA tips covering system tasks, files, browsers, terminals, productivity apps, developer tools, and UI automation. Search by keyword or category, then execute a result by its runnable ID.

A local knowledge base can add or override bundled tips without changing the package. It defaults to ~/.macos-automator/knowledge_base; see configuration and permissions for its layout and override rules.

Configuration

Variable

Values

Default

LOG_LEVEL

DEBUG, INFO, WARN, ERROR

INFO

KB_PARSING

lazy, eager

lazy

LOCAL_KB_PATH

Absolute path to a custom knowledge base

~/.macos-automator/knowledge_base

lazy loads the knowledge base on first use; eager loads it at server startup. More detail is in configuration and permissions.

Troubleshooting

  • Permission errors such as -1743 or -10004 usually mean the host application needs Automation or Accessibility access.

  • Script syntax errors are easiest to isolate with include_executed_script_in_output and include_substitution_logs, then reproduce in Script Editor.

  • Use an absolute POSIX path with script_path, and raise timeout_seconds for scripts that legitimately need more than 60 seconds.

  • JXA normally works best with output_format_mode: "direct"; the default auto mode selects it for JXA.

See Debugging AppleScript and JXA for a longer diagnostic guide.

Development

pnpm install
pnpm run build
pnpm test
pnpm run lint
pnpm run validate

The repository uses pnpm 11 and Node.js 24. The development guide covers local server setup and knowledge-base contributions.

Community

Report bugs and propose scripts in GitHub Issues.

License

MIT

Available Tools

2 tools
execute_scriptA
Destructive

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.

Inputs: language, arguments, input_data, script_path, +7 more.

get_scripting_tipsA
Read-only

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.

Inputs: limit, category, search_term, list_categories, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.9/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one discovers automation solutions and the other executes scripts. There is no overlap or ambiguity in their roles.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern in snake_case: 'execute_script' and 'get_scripting_tips'. The naming is predictable and readable.

    Tool Count4/5

    While only two tools exist, each serves an essential role in the discovery-execution workflow. The count is slightly below the typical range but is reasonable for the server's focused purpose.

    Completeness5/5

    The combination of a knowledge base for discovery and a general-purpose execution tool covers the full lifecycle of macOS automation. Arbitrary AppleScript/JXA can be executed, so there are no obvious dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Provides a Model Context Protocol server for executing AppleScript and JavaScript for Automation scripts on macOS, featuring a knowledge base of pre-defined scripts and supporting automation of macOS applications and system functions.
      2
      667 npm
      883
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables execution of AppleScript and JavaScript for Automation scripts on macOS, allowing programmatic control of applications and system functions through a rich knowledge base of pre-defined scripts.
      2
      9
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables the execution of AppleScript and JavaScript for Automation (JXA) on macOS to control applications, system events, and shell commands. It provides native automation capabilities with a security layer that permits most operations while specifically blocking file deletion commands.
      1
      6
      MIT