Applescript MCP README

AppleScript MCP Server (Dual access: python and node.js)

Overview

A Model Context Protocol (MCP) server that lets you run AppleScript code to interact with Mac. This MCP is intentionally designed to be simple, straightforward, intuitive, and require minimal setup.

I can't believe how simple and powerful it is. The core code is <100 line of code.

https://github.com/user-attachments/assets/b85e63ba-fb26-4918-8e6d-2377254ee388

Features

Run AppleScript to access Mac applications and data
Interact with Notes, Calendar, Contacts, Messages, and more
Search for files using Spotlight or Finder
Read/write file contents and execute shell commands
Remote execution support via SSH

Example Prompts

Code

Create a reminder for me to call John tomorrow at 10am

Code

Add a new meeting to my calendar for Friday from 2-3pm titled "Team Review"

Code

Create a new note titled "Meeting Minutes" with today's date

Code

Show me all files in my Downloads folder from the past week

Code

What's my current battery percentage?

Code

Show me the most recent unread emails in my inbox

Code

List all the currently running applications on my Mac

Code

Play my "Focus" playlist in Apple Music

Code

Take a screenshot of my entire screen and save it to my Desktop

Code

Find John Smith in my contacts and show me his phone number

Code

Create a folder on my Desktop named "Project Files"

Code

Open Safari and navigate to apple.com

Code

Tell me how much free space I have on my main drive

Code

List all my upcoming calendar events for this week

Usage with Claude Desktop

Node.js

config.json

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

Python (uvx)

No clone needed — run directly from the git repo:

config.json

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

Python (local development)

For local development, clone the repo and use uv to run from source:

Code

brew install uv
git clone https://github.com/peakmojo/applescript-mcp.git

config.json

{
  "mcpServers": {
    "applescript_execute": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/repo",
        "run",
        "mcp-server-applescript"
      ]
    }
  }
}

Development

Setup

bash

brew install uv
uv sync --dev

Run all checks (in parallel)

bash

uv run check

This runs linting, formatting, type checking, and tests with 100% coverage — all in parallel.

Individual commands

bash

uv run lint        # ruff linter
uv run format      # ruff auto-format
uv run typecheck   # pyrefly type checker
uv run test        # pytest with 100% coverage enforcement

Docker Usage

When running in a Docker container, you can use the special hostname host.docker.internal to connect to your Mac host:

Configuration

config.json

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

This allows your Docker container to execute AppleScript on the Mac host system. Make sure:

SSH is enabled on your Mac (System Settings → Sharing → Remote Login)
Your user has proper permissions
The correct credentials are provided in the config