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.
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"
// 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"
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)
// 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 "
Quarterly Report
Sales increased by 15%
"
// 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
AppleScriptFramework (framework.ts): The main server class that:
Manages MCP protocol communication
Handles tool registration and execution
Provides logging functionality
Executes AppleScript commands
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