Skip to main content
Glama
schmitzjimmy1-star

macos-automator-mcp

by schmitzjimmy1-star
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
languageNoSpecifies the scripting language. Crucial for `script_content` and `script_path` if not 'applescript'. Defaults to 'applescript'. Inferred if using `kb_script_id`.
argumentsNoOptional arguments to pass to the script. For AppleScript, these are passed to the main `run` handler. For JXA, these are passed to the `run` function.
input_dataNoOptional JSON object to provide named inputs for --MCP_INPUT placeholders in knowledge base scripts.
script_pathNoThe path to the script file to execute. Required if kb_script_id or script_content is not provided.
kb_script_idNoThe ID of a knowledge base script to execute. Replaces script_content and script_path if provided.
script_contentNoThe content of the script to execute. Required if kb_script_id or script_path is not provided.
timeout_secondsNoThe timeout for the script execution in seconds. Defaults to 60.
output_format_modeNoControls osascript output formatting. 'auto': (Default) Smart selection based on language (AppleScript: human_readable, JXA: direct). 'human_readable': AppleScript -s h. 'structured_error': AppleScript -s s. 'structured_output_and_error': AppleScript -s ss. 'direct': No -s flags (recommended for JXA).auto
report_execution_timeNoIf true, the tool will return an additional message containing the formatted script execution time. Defaults to false.
include_substitution_logsNoIf true, detailed logs of placeholder substitutions will be included in the output.
include_executed_script_in_outputNoIf true, the executed script content (after substitutions) or path will be included in the output.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations provide destructiveHint=true, and the description complements this with extensive behavioral details: timeout defaults, output formatting flags (-s h, -s s, etc.), placeholder substitution behavior, debug options (include_executed_script_in_output, include_substitution_logs), and execution time reporting. This goes well beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long due to tool complexity but is well-structured with numbered sections, code examples, and bullet lists. Every section provides actionable information—no filler. The front-loading of purpose and clear formatting make it easy to navigate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description thoroughly covers script input methods, options, and debugging aids. However, with no output schema, it does not explicitly describe the overall return value structure, only mentioning that certain flags add info to 'the response.' This is a minor gap given the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds substantial value: concrete examples for each script source, explanation of --MCP_INPUT placeholder mechanics, positional vs named arguments, default behavior for output_format_mode per language, and clear descriptions of all boolean options. This significantly exceeds schema-only information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource statement: 'Automate macOS tasks using AppleScript or JXA (JavaScript for Automation) to control applications like Terminal, Chrome, Safari, Finder, etc.' This clearly distinguishes it from the sibling tool get_scripting_tips, which is for finding scripts, not executing them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly names the alternative tool: 'Use get_scripting_tips to find IDs and inputs.' It also provides clear when-to-use guidance for each script source (kb_script_id recommended, script_content for simple/dynamic, script_path for path-based), and explains when to specify language and other options.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results to return. Default is 10.
categoryNoSpecific category of tips. If omitted with no `search_term`, lists all categories.
search_termNoKeyword to search within tip titles, content, keywords, or IDs.
list_categoriesNoIf true, returns only the list of available categories and their descriptions. Overrides other parameters.
refresh_databaseNoIf true, forces a reload of the knowledge base before processing the request.

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond the readOnlyHint annotation by disclosing output formats (Markdown), fuzzy search behavior, category tree structure, and the refresh_database behavior (forces reload, auto-refresh). It clearly explains how list_categories overrides other parameters, which is a subtle behavioral trait. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but meticulously structured with headings, bullet points, and examples. The core purpose is front-loaded, and every section earns its place by explaining use cases, parameter behavior, and best practices. No redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description fully covers return formats ('list of matching tips in Markdown format', 'Category tree in Markdown format'). It also covers all 5 parameters, their interplay, and the relationship with the sibling tool, making it complete for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema already covers all parameters (100% coverage), the description enriches each parameter with practical meaning: search_term examples, limit's interaction with category/list_categories, category path examples, and refresh_database's typical usage. It explains nuances like 'Does not apply if list_categories is true', which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific purpose: 'Discover how to automate any app on your Mac' via a knowledge base of AppleScript/JXA tips. It further distinguishes itself from the sibling tool execute_script by positioning itself as the 'FIRST CHOICE' for discovery, making the tool's role unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool versus alternatives: 'should be the FIRST CHOICE when aiming to automate macOS tasks... before attempting to write scripts from scratch.' It also points to the sibling tool ('Use its ID with execute_script tool'), and provides a 'Best Practices' section with concrete usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.4.6
    • First observedexecute_script
    • First observedget_scripting_tips
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

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

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • macOS Automator MCP Server

    steipete
    A
    license
    A
    quality
    A
    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
    867
    882
    MIT

  • macOS Automator MCP Server

    SuperCrazyKaizen
    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
    867
    8
    MIT

  • osascript MCP Server

    Akira-Papa
    F
    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
    -