AppleScript

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

<a href="https://glama.ai/mcp/servers/0t5gydjcqw"></a>

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 in Safari, save page content, get selected page/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 new 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 notification requires that you enable 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 all 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 in Mail.app | recipient, subject, body |
| list_emails | List emails from a mailbox | mailbox (optional), count (optional), unreadOnly (optional) |
| get_email | Get a 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 [email protected] 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 [email protected] about "Project Update"

Messages

| Command | Description | Parameters |
| ----------------- | -------------------------------------------- | --------------------------------------------------------- |
| list_chats | List available iMessage and SMS chats | includeParticipantDetails (optional, default: false) |
| get_messages | Get messages from the Messages app | limit (optional, default: 100) |
| search_messages | Search for messages containing specific text | searchText, sender (optional), chatId (optional), limit (optional, default: 50), daysBack (optional, default: 30) |
| compose_message | Open Messages app with pre-filled message 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 with formatting options) |
| createRawHtml | Create a note with direct HTML content | title, html |
| list | List notes, optionally from a specific folder| folder (optional) |
| get | Get a specific note by title | title, folder (optional) |
| search | Search for notes containing specific text | query, folder (optional), limit (optional, default: 5), includeBody (optional, default: true) |

Examples

// Create a new 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 with plain text | 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 applescript-mcp server is built using TypeScript and follows a modular architecture:

Core Components

1. AppleScriptFramework (framework.ts): The main server class that:
- Manages MCP protocol communication
- Handles tool registration and execution
- Provides logging functionality
- Executes AppleScript commands

2. Categories (src/categories/*.ts): Modular script collections organized by functionality:
- Each category contains related scripts (e.g., calendar, system, notes)
- Categories are registered with the framework in index.ts

3. Types (src/types/index.ts): TypeScript interfaces defining:
- ScriptDefinition: Structure for individual scripts
- ScriptCategory: Collection of related scripts
- LogLevel: Standard logging levels
- FrameworkOptions: Configuration options

Execution Flow

1. Client sends a tool request via MCP protocol
2. Server identifies the appropriate category and script
3. Script content is generated (static or dynamically via function)
4. AppleScript is executed via macOS osascript command
5. Results are returned to the client

Logging System

The framework includes a comprehensive logging system that:
- Logs to both stderr and MCP logging protocol
- Supports multiple severity levels (debug, info, warning, error, etc.)
- Provides detailed execution information for troubleshooting

Development

Setup

```bash