macOS Automator

You run a macOS Automator MCP Server to remotely execute AppleScript and JavaScript for Automation (JXA) on macOS. It provides a knowledge base of predefined scripts and supports inline scripts, script files, and argument passing, enabling you to automate macOS tasks from an MCP-driven workflow.

How to use

You use this MCP server by calling it through an MCP client. The server accepts commands to run AppleScript or JXA either from inline content, from a script file, or from a predefined script in its knowledge base. You can pass arguments and structured input to tailor each run, and you can choose how the output is formatted.

How to install

Prerequisites you need before starting:

• Node.js (version 18 or newer is recommended)
• macOS
• A user account with permission to control apps via Automation and Accessibility

Configuration and usage notes

The primary way to run the server is by using a package runner to pull the latest MCP server package and start it. You configure your MCP client to point at the server as described in the setup snippet.

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

Running locally for development or direct use

If you prefer to run the server directly from a cloned copy for development, you can use a start script provided with the project. This approach lets you edit source code and test changes immediately.

Step-by-step commands to run locally (example flow):

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

Configure your MCP client to point to the start script in your cloned folder. Example configuration snippet:

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

The start.sh script will use tsx to run the TypeScript source directly if a compiled version isn’t found, or run the compiled version from dist/ if it is available. The LOG_LEVEL environment variable controls logging verbosity.

## Security, permissions, and notes

Important security warnings apply when running this server on macOS. Ensure you have explicit Automation and Accessibility permissions granted to the application running the MCP server (such as Terminal or your Node.js runtime). First-time prompts may appear when granting new permissions, and the server itself cannot grant these permissions for you.

Automation permissions let you control other applications. Accessibility permissions enable UI scripting with System Events to simulate clicks and keystrokes.

If a script attempts to control an application or access restricted UI elements, double-check the permission settings and re-run the request. Timeouts and script errors will appear in the usual output channels, and you can increase timeout\_seconds for long-running tasks.

## Troubleshooting

Permissions: verify Automation and Accessibility permissions for the server runner application in System Settings.

Script errors: test scripts in a dedicated editor or JXA/AppleScript runners to isolate syntax or runtime issues.

Timeouts: adjust timeout\_seconds to accommodate longer executions.

Output parsing: for JXA, use appropriate output modes to ensure clean results; if AppleScript output parsing is problematic, consider structured output modes.

## Knowledge base and tips

Discover available scripts and their usage by querying the server for scripting tips. You can look up categories, specific tips, or runables by ID to see how to pass arguments and inputs.

## Available tools

### execute\_script

Executes AppleScript or JXA scripts. Supports inline script\_content, script\_path, or kb\_script\_id references. Handles inputs via arguments and input\_data, with configurable timeout and output formatting.

### get\_scripting\_tips

Fetches tips, examples, and runnable details from the built-in knowledge base. Supports filtering by category, searching, and refreshing the KB.