Skip to content
Back to search

macos-automator-mcp

An MCP server to run AppleScript and JXA (JavaScript for Automation) to macOS.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/steipete--macos-automator-mcp/badge.svg)](/listings/steipete--macos-automator-mcp)

HTML

<a href="/listings/steipete--macos-automator-mcp"><img src="/api/listings/steipete--macos-automator-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 118 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # macOS Automator MCP 🤖 — Give your agent a Mac to operate
  2. ![macOS Automator MCP](assets/logo.png)
  3. [![CI](https://img.shields.io/github/actions/workflow/status/steipete/macos-automator-mcp/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/steipete/macos-automator-mcp/actions/workflows/ci.yml)
  4. [![npm](https://img.shields.io/npm/v/@steipete/macos-automator-mcp?style=flat-square)](https://www.npmjs.com/package/@steipete/macos-automator-mcp)
  5. [![Node.js](https://img.shields.io/node/v/@steipete/macos-automator-mcp?style=flat-square)](https://nodejs.org/)
  6. [![macOS](https://img.shields.io/badge/platform-macOS-000000?style=flat-square&logo=apple)](https://www.apple.com/macos/)
  7. [![License](https://img.shields.io/github/license/steipete/macos-automator-mcp?style=flat-square)](LICENSE)
  8. 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.
  9. ## Install
  10. 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.
  11. ```json
  12. {
  13. "mcpServers": {
  14. "macos_automator": {
  15. "command": "npx",
  16. "args": ["-y", "--package", "@steipete/macos-automator-mcp", "macos-automator-mcp"]
  17. }
  18. }
  19. }
  20. ```
  21. If your client has a separate package field, use `@steipete/macos-automator-mcp` without `@latest`.
  22. ## Quick start
  23. Restart your MCP client after adding the configuration. First, ask it to call `get_scripting_tips` with a small search:
  24. ```json
  25. {
  26. "search_term": "Safari front tab URL",
  27. "limit": 3
  28. }
  29. ```
  30. Then verify script execution with a read-only inline script through `execute_script`:
  31. ```json
  32. {
  33. "script_content": "return \"Hello from macOS Automator\""
  34. }
  35. ```
  36. The result is `Hello from macOS Automator`. Calls that control applications or the user interface may prompt for macOS permissions.
  37. ## Tools
  38. | Tool | Purpose |
  39. | -------------------- | ---------------------------------------------------------------------- |
  40. | `get_scripting_tips` | List knowledge-base categories or search for AppleScript and JXA tips. |
  41. | `execute_script` | Run one inline script, script file, or knowledge-base script ID. |
  42. 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`.
  43. `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](docs/tool-reference.md) for every input and response option.
  44. ## Permissions
  45. The application that launches the MCP server—such as Terminal, an editor, or a desktop MCP client—owns its macOS privacy permissions:
  46. - Grant **Automation** access when scripts control Finder, Safari, Mail, or another application.
  47. - Grant **Accessibility** access when scripts use System Events for clicks, keystrokes, menus, or other UI scripting.
  48. macOS may show a first-use prompt for each target application. The server cannot grant these permissions itself. See [configuration and permissions](docs/configuration.md) for setup and common error codes.
  49. ## Knowledge base
  50. 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.
  51. 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](docs/configuration.md#local-knowledge-base) for its layout and override rules.
  52. ## Configuration
  53. | Variable | Values | Default |
  54. | --------------- | ---------------------------------------- | ----------------------------------- |
  55. | `LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR` | `INFO` |
  56. | `KB_PARSING` | `lazy`, `eager` | `lazy` |
  57. | `LOCAL_KB_PATH` | Absolute path to a custom knowledge base | `~/.macos-automator/knowledge_base` |
  58. `lazy` loads the knowledge base on first use; `eager` loads it at server startup. More detail is in [configuration and permissions](docs/configuration.md).
  59. ## Troubleshooting
  60. - Permission errors such as `-1743` or `-10004` usually mean the host application needs Automation or Accessibility access.
  61. - Script syntax errors are easiest to isolate with `include_executed_script_in_output` and `include_substitution_logs`, then reproduce in Script Editor.
  62. - Use an absolute POSIX path with `script_path`, and raise `timeout_seconds` for scripts that legitimately need more than 60 seconds.
  63. - JXA normally works best with `output_format_mode: "direct"`; the default `auto` mode selects it for JXA.
  64. See [Debugging AppleScript and JXA](docs/debugging_applescript.md) for a longer diagnostic guide.
  65. ## Development
  66. ```sh
  67. pnpm install
  68. pnpm run build
  69. pnpm test
  70. pnpm run lint
  71. pnpm run validate
  72. ```
  73. The repository uses pnpm 11 and Node.js 24. The [development guide](docs/DEVELOPMENT.md) covers local server setup and knowledge-base contributions.
  74. ## Community
  75. Report bugs and propose scripts in [GitHub Issues](https://github.com/steipete/macos-automator-mcp/issues).
  76. <a href="https://glama.ai/mcp/servers/@steipete/macos-automator-mcp">
  77. <img width="380" height="200" src="https://glama.ai/mcp/servers/@steipete/macos-automator-mcp/badge" alt="macOS Automator MCP server on Glama" />
  78. </a>
  79. ## License
  80. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.