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

# Clone the repository
git clone <repository-url>
cd mcp-mac

# Install dependencies
npm install

# Build the project
npm run build

E.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-name

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:

1. Search for "John Smith" in Contacts
2. Retrieve his contact details
3. Check your Mail inbox count
4. 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 scripts

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