MCP-AppleScript MCP Server

Local setup required. This server has to be cloned and prepared on your machine before you register it in Claude Code.
1

Set the server up locally

Run this once to clone and prepare the server before adding it to Claude Code.

Run in terminal
git clone https://github.com/frouaix/MCPAppleScript
cd MCPAppleScript

Then follow the repository README for any remaining dependency or build steps before continuing.

2

Register it in Claude Code

After the local setup is done, run this command to point Claude Code at the built server.

Run in terminal
claude mcp add mcp-applescript-e4bf -- node "<FULL_PATH_TO_MCPAPPLESCRIPT>/dist/index.js"

Replace <FULL_PATH_TO_MCPAPPLESCRIPT>/dist/index.js with the actual folder you prepared in step 1.

README.md

A local MCP server that exposes controlled AppleScript automation tools

MCP-AppleScript

A local MCP server that exposes controlled AppleScript automation tools to MCP clients on macOS.

[!CAUTION] This software can read, create, modify, and delete your personal data across Notes, Calendar, Reminders, Mail, Contacts, Messages, Photos, Music, Finder, and Safari.

By running this server you are granting an AI model the ability to interact with your macOS applications on your behalf. Although multiple safety layers exist (operation modes, per-app allowlists, destructive-action confirmation), no automated safeguard is foolproof. An unexpected prompt, a misconfigured policy, or a model hallucination could result in data loss, disclosure of private information, or unintended actions such as sending messages or emails.

You are solely responsible for:

  • Reviewing and understanding the configuration and policy model before enabling any app
  • Starting in readonly mode and only escalating when you understand the consequences
  • Keeping the number of enabled apps to the minimum you actually need
  • Never running in full mode unattended

This project is provided as-is, with no warranty. See LICENSE.

Overview

MCP-AppleScript provides a secure bridge between the Model Context Protocol and macOS automation via AppleScript. It consists of two components:

  • MCP Server (TypeScript/Node.js): Handles the MCP protocol, tool schemas, configuration, validation, logging, and policy enforcement
  • Swift Executor: Executes AppleScript commands via NSAppleScript and returns structured JSON results

Tools

All 10 Apple apps are accessed through generic app.* tools with an app parameter:

Tool Mode Description
applescript.ping readonly Health check — returns server version and supported apps
applescript.get_mode readonly Get current operation mode and enabled tools
applescript.set_mode readonly Change operation mode (readonly/create/full)
app.list_containers readonly List containers (folders, calendars, mailboxes, playlists, etc.)
app.list readonly List items in a container with pagination
app.get readonly Get a single item by ID
app.search readonly Search/filter items
app.create create Create a new item
app.action create App-specific actions (send, play, complete, do_javascript, etc.)
applescript.run_template create Execute a registered template by ID (policy-gated)
app.update full Update an item (confirmation required)
app.delete full Delete an item (confirmation required)
applescript.run_script full Execute raw AppleScript (confirmation required)

Supported Apps

Notes, Calendar, Reminders, Mail, Contacts, Messages, Photos, Music, Finder, Safari

Operation Modes

The server starts in readonly mode by default. Use applescript.set_mode to change modes on-the-fly:

Mode Description Available Tools
readonly No creation, editing, or deleting ping, get_mode, set_mode, app.list/get/search/list_containers
create Readonly + creation allowed + app.create, app.action, run_template
full All operations, potentially destructive + app.update, app.delete, run_script (requires confirmation)

When the mode changes, the client is notified via notifications/tools/list_changed and will only see tools available in the current mode.

Destructive Action Confirmation

In full mode, destructive tools (app.update, app.delete, run_script) require user confirmation:

  1. If the MCP client supports elicitation, a confirmation dialog is shown
  2. Otherwise, a confirmation token is returned — pass it back in a second call to confirm

Requirements

  • macOS 12.0 or later
  • Node.js 20+ (only for building from source)
  • Swift 5.9+ (only for building from source)
  • pnpm 8+ (only for building from source)

Installation

Option 1: Download pre-built binary (.dmg)

Download the latest .dmg from GitHub Releases:

  1. Open the .dmg and copy mcp-applescript to /usr/local/bin/:
    sudo cp /Volumes/MCP-AppleScript\ */mcp-applescript /usr/local/bin/
  2. Create a config file:
    mkdir -p ~/.config/applescript-mcp
cat > ~/.config/applescript-mcp/config.json << 'EOF'
{
  "defaultMode": "readonly",
  "apps": {
    "com.apple.Notes": { "enabled": true },
    "com.apple.iCal": { "enabled": true },
    "com.apple.reminders": { "enabled": true },
    "com.apple.mail": { "enabled": true },
    "com.apple.Contacts": { "enabled": true }
  }
}
EOF
  3. Add to your MCP client config (see Claude Desktop below)

The pre-built binary is a self-contained executable with Node.js and the Swift executor

Tools (13)

applescript.pingHealth check returning server version and supported apps
applescript.get_modeGet current operation mode and enabled tools
applescript.set_modeChange operation mode (readonly/create/full)
app.list_containersList containers like folders, calendars, mailboxes, or playlists
app.listList items in a container with pagination
app.getGet a single item by ID
app.searchSearch or filter items
app.createCreate a new item
app.actionPerform app-specific actions like send, play, or complete
applescript.run_templateExecute a registered template by ID
app.updateUpdate an existing item
app.deleteDelete an item
applescript.run_scriptExecute raw AppleScript

Configuration

claude_desktop_config.json
{"mcpServers": {"applescript": {"command": "/usr/local/bin/mcp-applescript", "args": ["--config", "~/.config/applescript-mcp/config.json"]}}}

Try it

→List all my notes in the 'Work' folder.
→Create a new reminder to buy groceries at 5 PM today.
→Search for emails from my manager in the last 24 hours.
→Play my 'Focus' playlist in Music.
→Get the details of the calendar event titled 'Team Sync'.

Frequently Asked Questions

What are the key features of MCP-AppleScript?

Secure bridge between MCP and macOS automation. Policy-based allowlists for specific macOS applications. Three operation modes: readonly, create, and full. Destructive action confirmation for updates and deletions. Supports Notes, Calendar, Reminders, Mail, Contacts, Messages, Photos, Music, Finder, and Safari.

What can I use MCP-AppleScript for?

Automating the creation of meeting notes from calendar events. Syncing tasks between AI-managed project boards and Apple Reminders. Searching and retrieving information from local Apple Mail or Notes. Triggering system-level actions like playing music or managing files via AI.

How do I install MCP-AppleScript?

Install MCP-AppleScript by running: sudo cp /Volumes/MCP-AppleScript\ */mcp-applescript /usr/local/bin/

What MCP clients work with MCP-AppleScript?

MCP-AppleScript works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep MCP-AppleScript docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.
Open Conare
View all other servers →

Related MCP Servers

Nuclear
Free, open-source music player without ads or tracking.
other17.1K stars
Domain Check
Fast domain availability checker with RDAP/WHOIS lookup and batch checking.
other253 stars
Ableton MCP Extended
Control Ableton Live using natural language via AI assistants
other142 stars
US Government Open Data MCP
MCP Server + TypeScript SDK for 40+ U.S. Government APIs
other90 stars
Garmin Connect
Access your fitness, health, and training data from MCP clients.
other71 stars
BinjaLattice MCP
Secure communication protocol for Binary Ninja and MCP servers
other61 stars