home / mcp / applescript mcp server

AppleScript MCP Server

A dual-access MCP server that runs AppleScript to automate macOS apps and data with both Node.js and Python workflows.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "peakmojo-applescript-mcp": {
      "command": "npx",
      "args": [
        "@peakmojo/applescript-mcp"
      ]
    }
  }
}

This MCP Server lets you run AppleScript on a Mac from a client, enabling remote control of applications, data, and tasks. It provides simple, dual access via Node.js and Python runtimes, so you can choose the workflow that fits your setup.

How to use

You connect to the AppleScript MCP Server using your preferred MCP client and run commands that execute AppleScript snippets on your Mac. Typical actions include interacting with Notes, Calendar, Contacts, and Messages; searching files with Spotlight or Finder; reading and writing files; running shell commands; and performing remote tasks over SSH. Use the Node.js-based or Python-based configuration to run the server locally, then point your MCP client at the corresponding server entry to execute AppleScript code remotely.

How to install

Prerequisites depend on the runtime you choose. Make sure you have Node.js and npm installed for the Node.js approach, or Python tooling available with uv for the Python approach.

# Node.js path (recommended for quick setup)
npx @peakmojo/applescript-mcp

# Python path (requires uv runtime)
brew install uv
git clone <your-repo-or-directory-containing-server> 
# then run the Python server as described in the next step

Additional setup notes

If you are deploying in a Docker container, you can connect to your Mac host using the special hostname host.docker.internal. You will typically configure the MCP client to run commands that forward to the host Mac for AppleScript execution.

Tools and capabilities

The server exposes actionable capabilities for interacting with macOS apps and files. You can run AppleScript to control applications, read and write files, perform shell operations, and query system information. You can also perform remote actions such as SSH-based execution and calendar or note management from a distant client.

Troubleshooting and tips

Verify that the Mac you want to control allows remote access and that the MCP client is configured to reach the correct server entry. If you use Docker, ensure the Mac host is reachable from inside the container and that SSH permissions are correctly set on the Mac. If commands do not execute, double-check AppleScript syntax and the environment in which the server runs (Node.js versus Python runtime).

Available tools

run_apple_script

Execute AppleScript to control macOS applications and system data.

manage_notes

Create, read, and manage notes via AppleScript.

manage_calendar

Create calendar events and read upcoming events.

manage_contacts

Search and fetch contact details.

spotlight_search

Search for files using Spotlight or Finder.

read_write_files

Read and write file contents and execute shell commands.

remote_execution

Execute AppleScript remotely over SSH.

screenshot

Capture screenshots of the screen and save to disk.

list_running_apps

List all currently running applications.

play_music

Play a playlist in Apple Music.

battery_status

Query current battery percentage.