home / mcp / osascript mcp server

osascript MCP Server

Runs macOS osascript (AppleScript and JXA) with safe defaults and a deletion-blocking policy.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "akira-papa-osascript-mcp-1": {
      "command": "node",
      "args": [
        "/path/to/osascript-mcp/server/index.js"
      ],
      "env": {
        "OSASCRIPT_TIMEOUT": "30000",
        "OSASCRIPT_LOG_SCRIPTS": "true"
      }
    }
  }
}

You can run macOS osascript-based scripts safely from a dedicated MCP server. This enables you to execute AppleScript and JavaScript for Automation (JXA) with controlled permissions, including convenient one-click installation on macOS desktops.

How to use

You interact with the osascript MCP Server through an MCP client. Start the server locally, then send AppleScript or JXA commands to run on your Mac. The server allows most actions, with a safety boundary that blocks only deletion-related shell commands to prevent data loss. Use it to automate Finder queries, System Events interactions, and controls for applications like Safari, Music, or Calendar.

How to install

Prerequisites you need before installation:

Node.js must be installed on your macOS machine.
npm or npx should be available to run MCP tooling.

Option 1: Install from MCPB package (recommended)

1. Download the ".mcpb" file.

2. Drag and drop the MCPB package onto Claude Desktop.

3. Allow the installation when prompted.

Option 2: Manual configuration

Add the MCP server to Claude Desktop’s configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json with the following snippet.

Configuration snippet

{
  "mcpServers": {
    "osascript": {
      "command": "node",
      "args": ["/path/to/osascript-mcp/server/index.js"],
      "env": {
        "OSASCRIPT_TIMEOUT": "30000",
        "OSASCRIPT_LOG_SCRIPTS": "true"
      }
    }
  }
}

Start and test locally

To run the server directly for testing, execute the Node script with the provided arguments.

node /path/to/osascript-mcp/server/index.js

Available tools

AppleScript execution

Executes native AppleScript commands against macOS apps and system components.

JXA execution

Runs JavaScript for Automation (JXA) to automate macOS apps.

Shell command execution

Allows running shell commands (except deletions) from scripts.

Finder operations

Interacts with Finder to query and manipulate files and folders.

System Events interactions

Uses System Events to perform keystrokes and key codes.

Application control

Controls and queries current state of applications like Safari, Music, Calendar, etc.