macOS Automator MCP Server

How to use

You will connect your MCP client to the macOS Automator MCP server to control AppleScript and JXA scripts on your Mac. Start by enabling the server as an MCP connection, then choose a knowledge-base script or provide a custom script to execute. You can reference built-in scripts for common tasks such as toggling dark mode, collecting data from apps, or performing UI automation using accessibility features. Use the execute_script tool to run either inline scripts, a file path, or a predefined knowledge-base script by its ID. When running a knowledge-base script, you can pass inputs and arguments to tailor the behavior for your workflow.

How to install

Prerequisites: you need Node.js version 18 or newer and macOS. You must grant Automation and Accessibility permissions to the application running the MCP server (for example, Terminal or your Node.js runtime). These permissions are configured in macOS System Settings under Privacy & Security.

Quick start using MCP client integration (no local install required): you can deploy the server via npx so you don’t have to install anything globally. Add this server configuration to your MCP client so automation begins immediately.

Quick start with MCP client

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

Robot Workshop Mode (Local Development)

If you want to tinker locally, you can clone the project and run it from source. This is useful for developing or testing custom scripts before you publish them.

Steps to follow locally:

git clone https://github.com/steipete/macos-automator-mcp.git
cd macos-automator-mcp
npm install

Configure your MCP client for local development

Point your MCP client to the absolute path of the start script inside your cloned repository. This allows you to run the server directly from source using TypeScript (tsx) when a compiled version isn’t present.

{
  "mcpServers": {
    "macos_automator_local": {
      "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh",
      "env": {
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Security and permissions

The server requires explicit user permissions for automation and accessibility. Grant checks for Automation and Accessibility under macOS Privacy & Security to the application running the server (for example, Terminal). These prompts may appear the first time you attempt to control a new application.

Knowledge base and scripting tips

Use the built-in knowledge base to discover onboarding scripts or fetch tips for specific apps and tasks. You can list categories, search for scripts by keyword, or request runnable tips to see how to structure inputs and arguments.

Typical script usage includes selecting a knowledge-base script by its ID and optionally supplying input_data or arguments to parameterize the run.

Robot Toolbox usage examples

The server can run a variety of automation tasks. Examples include controlling apps like Safari, Finder, Mail, or System Settings, playing with the clipboard, or triggering system notifications. You can embed these in your MCP client requests to automate your daily Mac workflows.

Troubleshooting

If you see Access Denied messages, confirm that Terminal (or the running server app) has Automation and Accessibility permissions enabled. If scripts don’t execute as expected, test the script in Script Editor, verify absolute paths, and adjust the timeout. If a task requires more time, increase timeout_seconds accordingly.

Notes on local knowledge bases

Local knowledge bases can override embedded ones when IDs collide. You can place custom tips under your local KB path, and they will be preferred when IDs match. This enables you to personalize and extend the automation capacity without altering core files.

Developer notes and tools

This server exposes tools to execute scripts, fetch scripting tips, and query accessibility UI. You can view tips, run pre-defined scripts, and inspect UI elements to automate complex interactions across apps.

App-wide capabilities and examples

You can launch quick automations such as toggling dark mode, reading clipboard content, creating folders in Finder, or querying Safari to get the current tab URL. These scripts can be invoked via knowledge-base IDs or custom script content.

execute_script

Runs AppleScript or JXA scripts. Scripts can be supplied inline, as a file path, or via a knowledge-base ID. Supports inputs, timeouts, and various output formatting options.

get_scripting_tips

Searches the built-in knowledge base for automation tips and script definitions, returning a Markdown-formatted catalog of available scripts, languages, IDs, and usage notes.

accessibility_query

Uses the ax binary to inspect or perform actions on macOS UI elements. Supports querying attributes, navigation, and performing actions like AXPress on matched elements.