mcp-mac
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-mac search for John Smith in my contacts and get his phone number"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: iac-mcp
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
# Clone the repository
git clone <repository-url>
cd mcp-mac
# Install dependencies
npm install
# Build the project
npm run buildE.g usage with Q CLI
# Add to your Q CLI MCP configuration
q config mcp add mcp-mac ./dist/index.js
# Use in Q chat sessions
# The tools will be available as mcp-mac___tool-nameExample 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
mcp-mac/
├── src/index.ts # MCP server implementation
├── dist/ # Compiled JavaScript
├── docs/ # Project documentation
│ ├── PROJECT-CHARTER.md # Project governance
│ ├── DEVELOPMENT-GUIDE.md # Development processes
│ └── iterations/ # Implementation history
└── package.json # Dependencies and scriptsDocumentation
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
Available Tools
24 toolscalendar_create_eventC
Create new calendar event
Inputs: title (required), start_datetime (required), end_datetime (required), calendar, +1 more.
calendar_get_calendarsB
Get all calendars with event counts
Inputs: no named parameters.
calendar_get_today_eventsB
Get today's events across all calendars
Inputs: no named parameters.
calendar_get_upcoming_eventsC
Get upcoming events in date range
Inputs: days.
contacts_get_person_infoC
Get detailed information for a specific person
Inputs: person_name (required).
contacts_search_peopleC
Search for people by name in Contacts
Inputs: search_term (required).
discover_appsC
Discover AppleScript capabilities of a macOS application
Inputs: app_name (required), method (required), destination (required).
finder_get_current_folderA
Get path of currently viewed folder in frontmost Finder window
Inputs: no named parameters.
finder_get_selectionB
Get currently selected files/folders in Finder
Inputs: no named parameters.
mail_create_messageC
Create new email message with recipients, subject, and body
Inputs: to (required), subject (required), body (required), cc.
mail_get_accountsB
Get list of all Mail account names
Inputs: no named parameters.
mail_get_inbox_countB
Get unread message count in inbox
Inputs: no named parameters.
mail_get_total_inbox_countB
Get total message count in inbox
Inputs: no named parameters.
mail_send_messageC
Send the most recently created message
Inputs: no named parameters.
notes_create_noteC
Create new note with title and content
Inputs: title (required), content (required), folder.
notes_get_foldersB
Get all note folders with note counts
Inputs: no named parameters.
notes_get_recent_notesC
Get recently modified notes
Inputs: limit.
notes_search_notesC
Search notes by title or content
Inputs: query (required).
reminders_create_reminderC
Create new reminder with title, optional due date and list
Inputs: title (required), due_date, list, notes.
reminders_get_incomplete_remindersC
Get incomplete reminders across all lists
Inputs: limit.
reminders_get_listsB
Get all reminder lists with reminder counts
Inputs: no named parameters.
textedit_create_documentC
Create new TextEdit document with optional content
Inputs: content.
textedit_get_documentsB
Get list of open TextEdit documents
Inputs: no named parameters.
workflow_contact_to_texteditC
Get contact information and create formatted TextEdit document
Inputs: name (required), title.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Every tool has a clearly distinct purpose with no ambiguity, as each is prefixed by its domain (e.g., calendar_, contacts_, finder_) and specifies a unique action (e.g., create_event, get_calendars, get_selection). The domains are well-separated, preventing misselection.
Tool names follow a highly consistent verb_noun pattern with domain prefixes (e.g., calendar_create_event, contacts_search_people). All use snake_case uniformly, and the naming structure is predictable across all 24 tools, making them easily readable and organized.
With 24 tools, the count is slightly high but reasonable for the broad scope of macOS automation covering multiple domains like calendar, contacts, mail, and notes. Each tool earns its place by addressing specific tasks, though it borders on heavy for a single server.
The tool surface provides strong CRUD/lifecycle coverage across domains, with create, get, and search operations for most resources. Minor gaps exist, such as no update/delete for calendar events or notes, but agents can work around these for core workflows.
Related MCP Connectors
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables LLM applications to interact with macOS through AppleScript.33397MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI to dynamically discover and control native macOS applications (like Finder, Mail, Safari) through AppleScript/JXA automation without pre-built integrations.3MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude to automate macOS applications, manage files, control music, send messages, and more through AppleScript.29 npm1GPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI to control Apple Mac apps like Messages, Notes, Contacts, Mail, Reminders, Calendar, and Maps through natural language commands.MIT