Skip to main content
Glama

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 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

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 (c) Sami Cokar, 2025

Available Tools

24 tools
calendar_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

    B3.4/5.0

    Scored across 24 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI to dynamically discover and control native macOS applications (like Finder, Mail, Safari) through AppleScript/JXA automation without pre-built integrations.
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to automate macOS applications, manage files, control music, send messages, and more through AppleScript.
      29 npm
      1
      GPL 3.0