Overview

AppleScript MCP Server provides a lightweight Model Context Protocol (MCP) server that runs AppleScript on macOS. It exposes a minimal, predictable interface so other tools (for example, AI agents, automation orchestrators, or local apps) can execute AppleScript snippets to interact with the Mac environment. The server is intentionally simple — the core implementation is compact, requires little setup, and focuses on reliable execution of AppleScript tasks.

Use it to automate common macOS interactions (Notes, Calendar, Contacts, Finder, Spotlight, Messages, and system utilities) from other processes or remote containers. It also supports executing shell commands, reading/writing files, taking screenshots, and running remotely via SSH, making it useful for both local and containerized automation workflows.

Features

Execute arbitrary AppleScript code and return results
Interact with macOS apps: Notes, Calendar, Contacts, Messages, Music, Safari, and more
Search files via Spotlight or Finder queries
Read and write file contents on disk
Run shell commands and capture output
Take screenshots and save to specified locations
Remote execution support over SSH (run AppleScript on a Mac host from a container)
Simple integration via Node (npx) or Python (uv/uvx) runners
Minimal configuration and tiny codebase for easy auditing

Installation / Configuration

Install and run the MCP server in one of the supported ways below. The package is available on npm (Node) and can be run directly from the Git repository using uv/uvx for Python-based MCP runners.

Node (recommended for npx usage)

# Run directly with npx
npx @peakmojo/applescript-mcp

Configure as an MCP server in a JSON config (example used by Claude Desktop)

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

Python (run from git via uvx)

{
  "mcpServers": {
    "applescript_execute": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/peakmojo/applescript-mcp",
        "mcp-server-applescript"
      ]
    }
  }
}

Local development (clone and run with uv)

brew install uv
git clone https://github.com/peakmojo/applescript-mcp.git
uv --directory /path/to/applescript-mcp run mcp-server-applescript

Docker / remote host example

{
  "mcpServers": {
    "applescript_execute": {
      "command": "npx",
      "args": [
        "@peakmojo/applescript-mcp",
        "--remoteHost", "host.docker.internal",
        "--remoteUser", "yourusername",
        "--remotePassword", "yourpassword"
      ]
    }
  }
}

Notes for Docker: enable SSH on the macOS host (System Settings → Sharing → Remote Login), ensure credentials and permissions are correct, and use the special hostname host.docker.internal from containers on Docker Desktop.

Available Resources

The server exposes capabilities you can call from an MCP client. Common resources and operations include:

AppleScript execution: run raw AppleScript, return result or error
macOS apps: read/write/interact with Notes, Calendar, Contacts, Messages, Music, Safari
File operations: list directories, read and write files, create folders
Search: Spotlight and Finder queries (by name, date ranges, metadata)
System info: battery, disk space, running applications
Shell commands: execute bash/zsh commands and capture stdout/stderr
Screenshots: capture full-screen or window screenshots and save to disk
Remote execution: same operations via SSH on a remote Mac host

CLI flags (quick reference)

Flag	Purpose
–remoteHost	Hostname or IP for SSH remote execution
–remoteUser	SSH username for remote host
–remotePassword	SSH password (or use key-based auth)
–help	Show usage and available flags

Use Cases

Create calendar events or reminders from an external AI agent: Example prompt: “Add a meeting Friday 2pm–3pm titled ‘Team Review’.” The MCP server runs AppleScript to create the Calendar entry.
Manage notes and meeting minutes: Example prompt: “Create a note titled ‘Meeting Minutes’ with today’s date” — the server writes a new Notes item.
File searches and reporting: Example prompt: “Show all files in Downloads modified in the last 7 days” — run a Spotlight/Finder query and return a file list.
System diagnostics: Example prompt: “What’s my current battery percentage?” — run a small AppleScript that queries system power info and returns a numeric value.
Remote automation from containers: Run the server inside a Docker container but target the host macOS via SSH (host.docker.internal), allowing CI pipelines or containerized tools to trigger AppleScript tasks.
Media and window control: Example prompt: “Play my ‘Focus’ playlist in Apple Music” or “Open Safari and go to apple.com” — direct control of apps via AppleScript.

Development & Testing

For contributors:

Use uv to run dev tasks (install via Homebrew)
The project includes linting, formatting, type checking, and tests (run via uv run check)
Clone the repo to run or modify the server locally: https://github.com/peakmojo/applescript-mcp

Keep in mind: because this server executes scripts on a macOS host, audit any scripts or inputs carefully and follow least-privilege and secure credential practices for remote connections.

AppleScript MCP Server for Mac Automation