Mcp Osascript

[Demo]

Quick Start

Claude Desktop — one click. Download mcp-osascript-1.1.3.mcpb from the latest release and double-click it. Claude Desktop installs the extension itself.

Or add it to the config manually:

{  "mcpServers": {    "osascript": {      "command": "npx",      "args": ["-y", "mcp-osascript"]    }  }}

Add this to your Claude Desktop config (Settings → Developer → Edit Config), restart Claude, and you're ready.

{  "mcpServers": {    "osascript": {      "command": "npx",      "args": ["-y", "mcp-osascript"]    }  }}

claude mcp add osascript -- npx -y mcp-osascript

git clone https://github.com/m0rvayne/mcp-osascript.gitcd mcp-osascript && npm install# then use: "command": "node", "args": ["/path/to/mcp-osascript/server/index.js"]

Try These Prompts

Once installed, ask Claude:

Tools

18 typed tools, each with input validation, error classification, and permission-aware error messages.

Self-Correcting Menus

When Claude tries to click a menu item that doesn't exist, the server automatically returns the list of available items at that level — so Claude can retry with the correct name. No other MCP server does this.

User:   "Click File → Export as PDF in Preview"Claude: calls app_menu click ["File", "Export as PDF"]Server: "Menu item 'Export as PDF' not found in 'File'.         Available: ['New from Clipboard', 'Open...', 'Close', 'Save',         'Duplicate', 'Rename...', 'Export...', 'Export as PDF...']"Claude: calls app_menu click ["File", "Export as PDF..."]Server: "Clicked: File > Export as PDF..."

Why mcp-osascript?

Star counts are a popularity measure, not a quality one — both alternatives predate this project by months. The rows above are the things that differ in practice.

Security audits

Four red-team audit passes (adversarial agents run against the source, commissioned by the author — not a third-party certification), the most recent against v1.1.2 with three parallel agents covering the shell surface, AppleScript escaping, and information disclosure. It found six real defects, including a tool that silently annulled another tool's scheme allowlist and a concurrency slot that could leak until the server deadlocked. Every finding is fixed and carries a regression test. escapeAS was verified against 13 string-breakout candidates through real osascript — none escape.

Permissions

Tools work in three tiers:

• No permission needed — clipboard, notifications, URLs, apps, files, displays, Shortcuts. Works immediately.
• Automation — browser tabs, frontmost app. macOS prompts once per browser.
• Accessibility — keyboard, windows, menus, hide/unhide. Grant once in System Settings → Privacy & Security → Accessibility.
• Screen Recording — screenshots only. Grant in System Settings → Privacy & Security → Screen Recording.

Ask Claude to run check_permissions and it will tell you which of these are already granted, which tools each one unlocks, and exactly which settings pane to open for the rest. The probes are read-only and never trigger a permission prompt.

When a permission is missing, the server tells you exactly what to do:

"Accessibility permission required. Grant access to 'osascript'in System Settings > Privacy & Security > Accessibility."

Testing

npm test

84 integration tests covering all 18 tools — input validation, security boundaries (URL scheme blocking, prototype pollution, script size limits), timeout enforcement, permission error handling, and regressions for every finding of the security audit.

Requirements

• macOS 13+ (Ventura or later)
• Node.js 18+

License

MIT