applescript-mcp
A macOS MCP server on AppleScript: the agent drives Calendar, Mail, Messages, Notes, Finder, iTerm and Shortcuts
- 395 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent reads mail, conversations, notes and the clipboard, all of which is personal data
- The server sends messages, runs commands in iTerm and quits apps
- It needs automation permissions and Full Disk Access to work
Install
- Works in
Manual install
git clone https://github.com/joshrutkowski/applescript-mcp.git && cd applescript-mcp && npm install && npm run buildA build from source: the documentation offers no other install route. The result lands in dist/index.js.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads mail, conversations, notes and the clipboard, all of which is personal data
- The server sends messages, runs commands in iTerm and quits apps
- It needs automation permissions and Full Disk Access to work
This is third-party code. Review the repository files before installing.
What it does
The server lets an agent control a Mac through AppleScript. Each command runs a ready-made script through the system osascript utility and returns the result to the client. Tools are grouped into categories by app and function. In Calendar the agent creates an event and lists today's events. In Mail it prepares a new message, lists messages of a mailbox and finds one by subject, sender or date. Messages offers a chat list, reading and searching conversations and sending: with auto-send or by opening a window where the text stays a draft. Notes can be created with simple markup or from HTML, then read and searched. In Pages the agent creates a document with text. The other categories are the clipboard, Finder with file search and Quick Look, system notifications and Do Not Disturb, volume, dark mode, launching and quitting apps, running commands in iTerm and running Shortcuts with input. The architecture is modular: a new category is a separate file in src/categories.
Who it is for. For Mac owners who want to run their calendar, mail, notes and apps from a conversation with an agent, and for developers extending the script set.
Good fit when
- You want today's events or a new Calendar meeting from a single phrase
- You need to find a Mail message by subject or sender and read it
- You want to save meeting notes in Notes with headings and lists or find an old note
- You want to run your own Shortcuts with input from the chat
- You need to put text on the clipboard, preview a file with Quick Look or run a command in iTerm
Not a fit when
- You are on Windows or Linux: the server works only on macOS 10.15 and newer
- You need Safari and Reminders: the documentation lists them as planned
- The agent must not touch mail, messages and terminal commands: the server can send messages and run commands in iTerm with no separate read-only mode
Example request
What events do I have in Calendar today? Then find the email from Sarah about the project update in Mail and save its gist to a note titled ProjectMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
DEBUG- The value applescript-mcp* turns on detailed logging.
Limitations
The documented setup requires macOS 10.15 or later, Node.js 18 and a source build. The project has not been updated recently: last commit in April 2025. The license is MIT.
Grant application automation permissions in macOS settings; reading Messages needs Full Disk Access. The server has no separate per-call approval mechanism: it passes generated AppleScript to `osascript`. Use client controls to restrict iTerm commands and automatic message sending.
Retrieved mail, notes and messages return to the agent and may reach a cloud model. Debug mode logs script and system details. Calendar supports creation and today’s events; Safari and Reminders are still listed as planned.
How to disable. Remove the applescript-mcp-server entry from the client's mcp.json file and restart the client. Revoke the automation permissions and Full Disk Access in macOS system settings, in the privacy section. Removing the connection does not undo created events, documents or sent messages.
FAQ
How do I install applescript-mcp and connect it to a client?
Clone the repository, run npm install and npm run build, then add a server to mcp.json with the command node and the argument /path/to/applescript-mcp/dist/index.js. The documentation offers no ready package for npx.
Which macOS apps can applescript-mcp control?
Calendar, Mail, Messages, Notes, Pages, Finder, iTerm and Shortcuts, plus the clipboard, system notifications and settings: volume, dark mode, launching and quitting apps. Safari and Reminders are listed as planned.
Why do notifications from applescript-mcp not appear?
Notifications are sent by Script Editor, so enable them for it in System Settings under Notifications. Without that send_notification shows nothing.
How do I give applescript-mcp access to Messages?
Messages are read from a database, so the client needs Full Disk Access. The other apps need an automation permission in the Privacy and Security section.
Can the agent send a message or an email by itself through applescript-mcp?
The compose_message tool sends a message with the auto=true parameter. Without it Messages opens with the text filled in and a person sends it. The create_email tool only creates an email draft in Mail.
Discussion
No questions or reviews yet.
Related
MCP serversMCP server for AppleScript: the agent runs scripts and controls Mac apps, from Notes and Calendar to files
A Swift MCP server that lets an agent drive any macOS app: click, type and read the interface tree
An MCP server for macOS: the agent moves the mouse, types, manages windows and captures the screen when an app has no API
An MCP server for driving Windows: the agent opens apps, clicks and types, reads window and UI state, and works with files and PowerShell
A Node.js MCP server through which an agent controls Home Assistant devices and edits its automations
An MCP server helps an agent build and test Python automation tasks for Windows applications and Android devices.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| applescript-mcp (this card) | no | not required | 395 | |
| AppleScript MCP Server | no | not required | 466 | runs arbitrary AppleScript the agent composes, with no ready categories |
| MCP iCal Server | no | not required | 333 | a narrow server for the macOS calendar only, creating, finding and editing events |
README in short
Categories are separate TypeScript modules. A developer can add a missing action’s script and parameters, then rebuild the server. Existing tools use the system AppleScript runtime.