Enables AI-powered automation of macOS native applications including Finder (file management), Mail (email operations), Contacts (contact search and retrieval), Reminders (task management), Notes (note creation and search), TextEdit (document management), and Calendar (event management) through AppleScript.
mcp-mac
AI-powered automation of macOS Apple applications
This is a proof of concept to learn about AI and MacOS, and developed using with AI. I am unlikely to progress this any further.
mcp-mac enables AI agents to interact with macOS applications (Finder, Mail, Contacts, etc) using AppleScript through the Model Context Protocol (MCP). This allows AI assistants to perform tasks like searching contacts, managing files, and checking email on your behalf.
What is MCP?
The Model Context Protocol (MCP) is an open standard that allows AI applications to securely connect to external data sources and tools. mcp-mac implements an MCP server that provides AI agents with controlled access to your macOS applications.
Current Status
Available Tools
Finder: Get selected files, get current folder location
Mail: List accounts, get inbox unread/total count, create and send messages
Contacts: Search people, get contact information
Reminders: List lists, get incomplete reminders, create reminders
Notes: List folders, search/get recent notes, create notes
TextEdit: List documents, create documents
Calendar: List calendars, get today's/upcoming events, create events
Workflow: Composite tools for multi-app actions (e.g., Contacts to TextEdit)
Discovery: Introspect application capabilities
Quick Start
Prerequisites
macOS (tested on MacOS 26.2)
Node.js 18
Installation
E.g usage with Q CLI
Example Workflow
Once set up, you can ask an AI assistant to:
"Get John Smith's contact information and also check how many unread emails I have"
The AI will use the mcp-mac tools to:
Search for "John Smith" in Contacts
Retrieve his contact details
Check your Mail inbox count
Provide a combined response
Project Structure
Documentation
Architecture - System design and technical details
Technical Lessons - AppleScript quirks and implementation details
Privacy & Security
mcp-mac accesses your personal data (contacts, email, files) through standard macOS AppleScript interfaces. All data processing happens locally on your machine. No data is transmitted to external servers.
Important: Only use with trusted AI applications and review any automation requests before execution.
Disclaimer
This software is provided "as is," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non-infringement. The entire risk as to the quality and performance of the program is with you. In no event shall the author or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. You assume all responsibility for the use of this software on your system, and you are accountable for any actions or consequences that arise from its use.
License
Licensed under the MIT license. MIT
Copyright
Copyright (c) Sami Cokar, 2025