Skip to main content
Glama
schmitzjimmy1-star

macos-automator-mcp

by schmitzjimmy1-star
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

execute_script

Destructive

Run AppleScript or JXA to automate macOS apps and system tasks. Supports knowledge base scripts, raw code, or file paths for flexible control.

Instructions

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.

Input Schema

TableJSON 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.

Tool Definition Quality

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.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/schmitzjimmy1-star/macos-automator-vision-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server