📌Overview

Purpose: To provide a Model Context Protocol server enabling LLM applications to interact with macOS functionalities through AppleScript.

Overview: The applescript-mcp MCP Server streamlines communication between AI applications and macOS, allowing for control over various system functions, file management, notifications, and more via a standardized interface.

Key Features:

Calendar Management: Facilitates event and reminder handling, enabling users to manage their schedules efficiently.
Clipboard Operations: Allows copying, retrieving, and clearing of clipboard contents, enhancing information management capabilities.
Finder Integration: Users can quickly access files through commands for searching and selecting, improving productivity.
System Notifications: Enables sending notifications and toggling Do Not Disturb mode, keeping users informed without interruptions.
System Controls: Provides commands to control system settings like volume and dark mode, offering seamless user experience customization.
iTerm Integration: Supports executing commands and pasting content in iTerm, making terminal operations more accessible.

applescript-mcp MCP Server

A Model Context Protocol server enabling LLM applications to interact with macOS through AppleScript.
It provides a standardized interface for AI applications to control system functions, manage files, handle notifications, and more.

Features

🗓️ Calendar management (events, reminders)
📋 Clipboard operations
🔍 Finder integration
🔔 System notifications
⚙️ System controls (volume, dark mode, apps)
📟 iTerm terminal integration
📬 Mail (create new email, list emails, get email)
🔄 Shortcuts automation
💬 Messages (list chats, get messages, search messages, send a message)
🗒️ Notes (create formatted notes, list notes, search notes)
📄 Pages (create documents)

Planned Features

🧭 Safari (open, save page content, get selected tab)
✅ Reminders (create, get)

Prerequisites

macOS 10.15 or later
Node.js 18 or later

Available Categories

Calendar

Command	Description	Parameters
`add`	Create calendar event	`title`, `startDate`, `endDate`, `calendar` (optional)
`list`	List today's events	None

Examples:

// Create a calendar event
Create a calendar event titled "Team Meeting" starting tomorrow at 2pm for 1 hour

// List today's events
What events do I have scheduled for today?

Clipboard

Command	Description	Parameters
`set_clipboard`	Copy to clipboard	`content`
`get_clipboard`	Get clipboard contents	None
`clear_clipboard`	Clear clipboard	None

Examples:

// Copy text to clipboard
Copy "Remember to buy groceries" to my clipboard

// Get clipboard contents
What's currently in my clipboard?

// Clear clipboard
Clear my clipboard

Finder

Command	Description	Parameters
`get_selected_files`	Get selected files	None
`search_files`	Search for files	`query`, `location` (optional)
`quick_look`	Preview file	`path`

Examples:

// Get selected files in Finder
What files do I currently have selected in Finder?

// Search for files
Find all PDF files in my Documents folder

// Preview a file
Show me a preview of ~/Documents/report.pdf

Notifications

Note: Sending notifications requires enabling notifications in System Settings > Notifications > Script Editor.

Command	Description	Parameters
`send_notification`	Show notification	`title`, `message`, `sound` (optional)
`toggle_do_not_disturb`	Toggle DND mode	None

Examples:

// Send a notification
Send me a notification with the title "Reminder" and message "Time to take a break"

// Toggle Do Not Disturb
Turn on Do Not Disturb mode

System

Command	Description	Parameters
`volume`	Set system volume	`level` (0-100)
`get_frontmost_app`	Get active app	None
`launch_app`	Open application	`name`
`quit_app`	Close application	`name`, `force` (optional)
`toggle_dark_mode`	Toggle dark mode	None

Examples:

// Set system volume
Set my Mac's volume to 50%

// Get active application
What app am I currently using?

// Launch an application
Open Safari

// Quit an application
Close Spotify

// Toggle dark mode
Switch to dark mode

iTerm

Command	Description	Parameters
`paste_clipboard`	Paste to iTerm	None
`run`	Execute command	`command`, `newWindow` (optional)

Examples:

// Paste clipboard to iTerm
Paste my clipboard contents into iTerm

// Run a command in iTerm
Run "ls -la" in iTerm

// Run a command in a new iTerm window
Run "top" in a new iTerm window

Shortcuts

Command	Description	Parameters
`run_shortcut`	Run a shortcut	`name`, `input` (optional)
`list_shortcuts`	List available shortcuts	`limit` (optional)

Examples:

// List available shortcuts
List all my available shortcuts

// List with limit
Show me my top 5 shortcuts

// Run a shortcut
Run my "Daily Note in Bear" shortcut

// Run a shortcut with input
Run my "Add to-do" shortcut with input "Buy groceries"

Mail

Command	Description	Parameters
`create_email`	Create a new email	`recipient`, `subject`, `body`
`list_emails`	List emails from mailbox	`mailbox` (optional), `count` (optional), `unreadOnly` (optional)
`get_email`	Get specific email by search	`subject` (optional), `sender` (optional), `dateReceived` (optional), `mailbox` (optional), `account` (optional), `unreadOnly` (optional), `includeBody` (optional)

Examples:

// Create a new email
Compose an email to john@example.com with subject "Meeting Tomorrow" and body "Hi John, Can we meet tomorrow at 2pm?"

// List emails
Show me my 10 most recent unread emails

// Get a specific email
Find the email from sarah@example.com about "Project Update"

Messages

Command	Description	Parameters
`list_chats`	List iMessage and SMS chats	`includeParticipantDetails` (optional, default: false)
`get_messages`	Get messages from Messages app	`limit` (optional, default: 100)
`search_messages`	Search messages by text	`searchText`, `sender` (optional), `chatId` (optional), `limit` (optional, default: 50), `daysBack` (optional, default: 30)
`compose_message`	Open Messages with pre-filled or auto-send	`recipient` (required), `body` (optional), `auto` (optional, default: false)

Examples:

// List available chats
Show me my recent message conversations

// Get recent messages
Show me my last 20 messages

// Search messages
Find messages containing "dinner plans" from John in the last week

// Compose a message
Send a message to 555-123-4567 saying "I'll be there in 10 minutes"

Notes

Command	Description	Parameters
`create`	Create a note with markdown-like formatting	`title`, `content`, `format` (optional)
`createRawHtml`	Create a note with HTML content	`title`, `html`
`list`	List notes, optionally by folder	`folder` (optional)
`get`	Get a specific note by title	`title`, `folder` (optional)
`search`	Search notes by text	`query`, `folder` (optional), `limit` (optional, default: 5), `includeBody` (optional, default: true)

Examples:

// Create a note with markdown formatting
Create a note titled "Meeting Minutes" with content "# Discussion Points\n- Project timeline\n- Budget review\n- Next steps" and format headings and lists

// Create a note with HTML
Create a note titled "Formatted Report" with HTML content "<h1>Quarterly Report</h1><p>Sales increased by <strong>15%</strong></p>"

// List notes
Show me all my notes in the "Work" folder

// Get a specific note
Show me my note titled "Shopping List"

// Search notes
Find notes containing "recipe" in my "Cooking" folder

Pages

Command	Description	Parameters
`create_document`	Create a new Pages document	`content`

Examples:

// Create a new Pages document
Create a Pages document with the content "Project Proposal\n\nThis document outlines the scope and timeline for the upcoming project."

Architecture

The server is built in TypeScript with a modular architecture:

Core Components

AppleScriptFramework:
- Manages MCP protocol communication
- Handles tool registration and execution
- Provides logging
- Executes AppleScript commands
Categories:
- Modular script collections based on functionality (e.g. calendar, system, notes)
- Registered with the framework
Types:
- Interfaces defining scripts, categories, log levels, and config options

Execution Flow

Client sends a tool request via MCP protocol
Server identifies category and script
Script content is generated (static or dynamic)
AppleScript is executed using osascript
Results returned to client

Logging System

Logs to stderr and MCP logging protocol
Supports multiple severity levels (debug, info, warning, error)
Detailed execution info for troubleshooting

Development

Setup

npm install
npm run build
# Launch MCP Inspector
npx @modelcontextprotocol/inspector node path/to/server/index.js args...

Adding New Functionality

Create category file src/categories/newcategory.ts:

import { ScriptCategory } from "../types/index.js";

export const newCategory: ScriptCategory = {
  name: "category_name",
  description: "Category description",
  scripts: [
    // Scripts go here
  ],
};

Add scripts:

{
  name: "script_name",
  description: "What the script does",
  schema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",
        description: "Parameter description"
      }
    },
    required: ["paramName"]
  },
  script: (args) => `
    tell application "App"
      // AppleScript code using ${args.paramName}
    end tell
  `
}

import { newCategory } from "./categories/newcategory.js";
// ...
server.addCategory(newCategory);

Advanced Script Development

Use dynamic script generation based on input
Process complex data like markdown to HTML

Debugging

Using MCP Inspector

npm run inspector

Logging

Enable debug logging:

DEBUG=applescript-mcp* npm start

Example Configuration

Add to mcp.json after build:

{
  "mcpServers": {
    "applescript-mcp-server": {
      "command": "node",
      "args": ["/path/to/applescript-mcp/dist/index.js"]
    }
  }
}

Common Issues

Permission errors: Check System Preferences > Security & Privacy > Privacy > Automation
Script failures: Test scripts in Script Editor.app before integration
Communication issues: Ensure stdio streams are not redirected
Database access: Some features require Full Disk Access permission

Resources

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

MIT License - see LICENSE for details