macos-automator-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@macos-automator-mcp Get the URL of the front Safari tab"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
macOS Automator MCP 🤖 — Give your agent a Mac to operate

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 |
| List knowledge-base categories or search for AppleScript and JXA tips. |
| 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 |
|
|
|
|
|
|
| Absolute path to a custom 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
-1743or-10004usually mean the host application needs Automation or Accessibility access.Script syntax errors are easiest to isolate with
include_executed_script_in_outputandinclude_substitution_logs, then reproduce in Script Editor.Use an absolute POSIX path with
script_path, and raisetimeout_secondsfor scripts that legitimately need more than 60 seconds.JXA normally works best with
output_format_mode: "direct"; the defaultautomode 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 validateThe 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
Available Tools
2 toolsexecute_scriptADestructive
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. Useget_scripting_tipsto find IDs and inputs. Supports placeholder substitution viainput_dataorarguments. 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): Forkb_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): Forscript_path(passes toon run argv/run(argv)). Forkb_script_id, used for positional args (e.g.,--MCP_ARG_1).
3. Execution Options (Optional):
language('applescript' | 'javascript'): Specify forscript_content/script_path(default: 'applescript'). Inferred forkb_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'): Controlsosascriptoutput formatting.'auto': Smart default - resolves to'human_readable'for AppleScript and'direct'for JXA.'human_readable': For AppleScript, uses-s hflag.'structured_error': For AppleScript, uses-s sflag (structured errors).'structured_output_and_error': For AppleScript, uses-s ssflag (structured output & errors).'direct': No special output flags (recommended for JXA).
include_executed_script_in_output(boolean, optional, default: false): Iftrue, 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): Forkb_script_id, includes detailed placeholder substitution logs.report_execution_time(boolean, optional, default: false): Iftrue, 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_tipsARead-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_termor browsing a specificcategory(withoutlist_categories: true). Does not apply iflist_categoriesis true.
Browsing by Category (Use
category):Parameter:
category(string, optional).Functionality: Shows tips from a specific category. Combine with
limitto control result count.Example:
category: "01_intro"orcategory: "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:
Always start with search: Use natural language queries to find solutions (e.g., "send email from Mail app").
Browse categories when exploring: Use
list_categories: trueto see available automation areas.Use specific IDs for execution: Once you find a script, use its ID with
execute_scripttool 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
Scored across 2 tools
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.
Both tool names follow a consistent verb_noun pattern in snake_case: 'execute_script' and 'get_scripting_tips'. The naming is predictable and readable.
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.
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
Related MCP Connectors
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Read-only AgentiScript concept search, catalog, authenticity, license, and approved asset discovery.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables running AppleScript code to interact with Mac applications and system features including Notes, Calendar, Contacts, Messages, file management, and more.1159 npm469MIT
- AlicenseAqualityFmaintenanceProvides 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.2667 npm883MIT
- AlicenseAqualityDmaintenanceA 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.29MIT
- AlicenseAqualityDmaintenanceEnables 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.16MIT