execute_script
Execute AppleScript or JavaScript for Automation (JXA) on macOS to automate tasks. Utilize pre-defined scripts, raw code, or local files. Supports input substitution, script debugging, and execution timeout settings.
Instructions
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, theirRunnable ID
s (which become thiskbScriptId
), and any required inputs (seeargumentsPrompt
fromget_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 theinputData
orarguments
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
.
- Primarily for
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'sargumentsPrompt
fromget_scripting_tips
. Less common for KB scripts thaninputData
.
- For
3. Execution Options:
language
(enum: 'applescript' | 'javascript', optional):- Specifies the scripting language.
- Crucial for
scriptContent
andscriptPath
if notapplescript
. 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
, usesosascript -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.
- If
includeExecutedScriptInOutput
(boolean, optional, default: false):- If
true
, the full script content (after placeholder substitutions for knowledge base scripts) or thescriptPath
will be appended to the successful output. Useful for verification and debugging.
- If
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 withinputData
/arguments
processing and how they are inserted into the script.
- Only applies to
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.
Input Schema
Name | Required | Description | Default |
---|---|---|---|
arguments | No | ||
includeExecutedScriptInOutput | No | ||
includeSubstitutionLogs | No | ||
inputData | No | ||
kbScriptId | No | ||
language | No | ||
scriptContent | No | ||
scriptPath | No | ||
timeoutSeconds | No | ||
useScriptFriendlyOutput | No |