The applescript-mcp server enables LLM applications to interact with macOS through AppleScript, providing control over various system functions and applications.
System Control: Set volume, get frontmost app, launch/quit apps, toggle dark mode, check battery status
Calendar Operations: Add events, list today's events
Finder & File Operations: Get selected files, search files, preview files
Clipboard Management: Get, set, and clear clipboard contents
Notification Management: Send notifications, toggle Do Not Disturb
iTerm Operations: Paste clipboard, run commands
Mail Operations: Create emails, list emails, get email
Messages: List chats, get messages, search messages, compose messages
Notes: Create formatted/HTML notes, list notes, search notes
Pages: Create documents
Shortcuts: Run shortcuts with optional input, list shortcuts
Allows interaction with macOS through AppleScript, including calendar management, clipboard operations, Finder integration, system notifications, system controls, and iTerm terminal integration
Required as a prerequisite for running the MCP server
Planned feature to allow opening pages in Safari, saving page content, and getting selected page/tab
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.
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
Clipboard
Command | Description | Parameters |
---|---|---|
set_clipboard | Copy to clipboard | content |
get_clipboard | Get clipboard contents | None |
clear_clipboard | Clear clipboard | None |
Examples
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
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
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
iTerm
Command | Description | Parameters |
---|---|---|
paste_clipboard | Paste to iTerm | None |
run | Execute command | command , newWindow (optional) |
Examples
Shortcuts
Command | Description | Parameters |
---|---|---|
run_shortcut | Run a shortcut | name , input (optional) |
list_shortcuts | List all available shortcuts | limit (optional) |
Examples
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
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
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
Pages
Command | Description | Parameters |
---|---|---|
create_document | Create a new Pages document with plain text | content |
Examples
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
- Types (
src/types/index.ts
): TypeScript interfaces defining:ScriptDefinition
: Structure for individual scriptsScriptCategory
: Collection of related scriptsLogLevel
: Standard logging levelsFrameworkOptions
: Configuration options
Execution Flow
- Client sends a tool request via MCP protocol
- Server identifies the appropriate category and script
- Script content is generated (static or dynamically via function)
- AppleScript is executed via macOS
osascript
command - 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
Adding New Functionality
1. Create Category File
Create src/categories/newcategory.ts
:
2. Add Scripts
3. Register Category
Update src/index.ts
:
Advanced Script Development
For more complex scripts, you can:
- Use dynamic script generation:
- Process complex data:
Debugging
Using MCP Inspector
The MCP Inspector provides a web interface for testing and debugging your server:
Logging
Enable debug logging by setting the environment variable:
Example configuration
After running npm run build
add the following to your mcp.json
file:
Common Issues
- Permission Errors: Check System Preferences > Security & Privacy > Privacy > Automation
- Script Failures: Test scripts directly in Script Editor.app before integration
- Communication Issues: Check stdio streams aren't being redirected
- Database Access: Some features (like Messages) 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
local-only server
The server can only run on the client's local machine because it depends on local resources.
Tools
Enables LLM applications to interact with macOS through AppleScript.
Related MCP Servers
- AsecurityAlicenseAqualityEnables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environmentLast updated -101,140243MIT License
- AsecurityAlicenseAqualityFacilitates controlling Apple Music on macOS via AppleScript through MCP commands, allowing users to manage playback, search for tracks, and create playlists.Last updated -1046MIT License
- AsecurityFlicenseAqualityEnables interaction with lightning addresses and common lightning tools via your LLM, providing Lightning Network functionality through natural language.Last updated -3111
- AsecurityAlicenseAqualityA Model Context Protocol server that enables running AppleScript code to interact with Mac applications and system features including Notes, Calendar, Contacts, Messages, file management, and more.Last updated -1814345MIT License