Apple Script

What is applescript-mcp?

applescript-mcp is a Model Context Protocol (MCP) server that enables you to execute AppleScript code to control your Mac. It is designed to be simple, intuitive, and requires minimal setup, allowing for full control over various Mac applications and data.

How to use applescript-mcp?

applescript-mcp can be used with Claude Desktop via Node.js or Python.

Node.js:

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

Python:

First, install uv (e.g., brew install uv). Then, clone the repository and configure the server:

{
  "mcpServers": {
    "applescript_execute": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/repo",
        "run",
        "src/applescript_mcp/server.py"
      ]
    }
  }
}

For Docker usage, you can connect to your Mac host using host.docker.internal and provide SSH credentials in the configuration. Ensure SSH is enabled on your Mac and user permissions are set correctly.

Key features of applescript-mcp

• AppleScript Execution: Run AppleScript to access Mac applications and data.
• Application Interaction: Interact with applications like Notes, Calendar, Contacts, Messages, and more.
• File Management: Search for files using Spotlight or Finder, read/write file contents, and execute shell commands.
• Remote Execution: Supports remote execution via SSH.

Use cases of applescript-mcp

applescript-mcp can be used for a wide range of automation tasks on your Mac, including:

• Creating reminders and calendar events.
• Managing notes and contacts.
• Searching for files and managing file system operations.
• Controlling media playback (e.g., Apple Music).
• Taking screenshots.
• Gathering system information (e.g., battery percentage, disk space).
• Opening applications and navigating to websites.

FAQ about applescript-mcp

Q: What is the core idea behind applescript-mcp? A: It's a simple and powerful MCP server that allows LLMs to run AppleScript code to fully control anything on a Mac without complex setup.

Q: Is it easy to set up? A: Yes, it's designed to be simple, straightforward, intuitive, and require minimal setup. The core code is less than 100 lines.

Q: Can I use it remotely? A: Yes, it supports remote execution via SSH, and you can configure it for Docker usage to connect to your Mac host.

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

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

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

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

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

What's my current battery percentage?

Show me the most recent unread emails in my inbox

List all the currently running applications on my Mac

Play my "Focus" playlist in Apple Music

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

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

Create a folder on my Desktop named "Project Files"

Open Safari and navigate to apple.com

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

List all my upcoming calendar events for this week

Usage with Claude Desktop

Node.js

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

Python

Install uv

brew install uv
git clone ...

Run the server

{
  "mcpServers": {
    "applescript_execute": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/repo",
        "run",
        "src/applescript_mcp/server.py"
      ]
    }
  }
}

Docker Usage

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

Configuration

{
  "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