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

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

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

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

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

Copy code
What's my current battery percentage?

Copy code
Show me the most recent unread emails in my inbox

Copy code
List all the currently running applications on my Mac

Copy code
Play my "Focus" playlist in Apple Music

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

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

Copy code
Create a folder on my Desktop named "Project Files"

Copy code
Open Safari and navigate to apple.com

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

Copy code
List all my upcoming calendar events for this week

Usage with Claude Desktop

Node.js

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

Python (uvx)

No clone needed — run directly from the git repo:

jsonCopy code
{
  "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:

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

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

Development

Setup

bashCopy code
brew install uv
uv sync --dev

Run all checks (in parallel)

bashCopy code
uv run check

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

Individual commands

bashCopy code
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

jsonCopy code
{
  "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:

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