Information
# applescript-mcp MCP Server
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.
[](https://github.com/joshrutkowski/applescript-mcp/actions/workflows/node.js.yml)
## 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 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 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 "
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 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 # Install dependencies npm install # Build the server npm run build # Launch MCP Inspector # See: https://modelcontextprotocol.io/docs/tools/inspector npx @modelcontextprotocol/inspector node path/to/server/index.js args... \`\`\` ### Adding New Functionality #### 1. Create Category File Create \`src/categories/newcategory.ts\`: \`\`\`typescript import \{ ScriptCategory \} from "../types/index.js"; export const newCategory: ScriptCategory = \{ name: "category_name", description: "Category description", scripts: [ // Scripts will go here ], \}; \`\`\` #### 2. Add Scripts \`\`\`typescript \{ 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 \` \} \`\`\` #### 3. Register Category Update \`src/index.ts\`: \`\`\`typescript import \{ newCategory \} from "./categories/newcategory.js"; // ... server.addCategory(newCategory); \`\`\` ### Advanced Script Development For more complex scripts, you can: 1. **Use dynamic script generation**: \`\`\`typescript script: (args) => \{ // Process arguments and build script dynamically let scriptContent = \`tell application "App"\n\`; if (args.condition) \{ scriptContent += \` // Conditional logic\n\`; \} scriptContent += \`end tell\`; return scriptContent; \} \`\`\` 2. **Process complex data**: \`\`\`typescript // Example from Notes category function generateNoteHtml(args: any): string \{ // Process markdown-like syntax into HTML let processedContent = content; if (format.headings) \{ processedContent = processedContent.replace(/^# (.+)$/gm, '