Repository avatar
AI Tools
v0.2.1
active

applesauce

com.akshitanchan/applesauce

One MCP server for Calendar, Reminders, Mail, Notes, Contacts and more on your Mac.

Documentation

applesauce logo

applesauce

One MCP server for the Apple apps on your Mac.

applesauce demo: an assistant plans a day with Calendar, Notes, Mail and Reminders (sample data)

applesauce is one small native program, written in Swift. It lets an AI assistant work with your Calendar, Reminders, Mail, Notes and Contacts. It can also run Shortcuts, search files with Spotlight, and use the clipboard. It talks to the assistant over MCP (the Model Context Protocol) on stdin and stdout.

  • Needs macOS 14 or newer. Works on Apple silicon and Intel.
  • No account, no cloud. Everything runs on your Mac.
  • Mail search is fast when it can read the Mail index (see Full Disk Access below).
  • Every error says what went wrong and how to fix it.

Tools

42 tools in 8 modules, plus doctor.

ModuleTools
calendarlist_calendars, list_events, search_events, get_event, create_event, update_event, delete_event
reminderslist_reminder_lists, list_reminders, search_reminders, get_reminder, create_reminder, update_reminder, complete_reminder, delete_reminder
maillist_accounts, list_mailboxes, search_mail, get_message, get_mail_attachment, create_draft, send_mail, reply, move_message, flag_message, mark_read, delete_message
noteslist_folders, search_notes, get_note, get_note_attachment, create_note, append_to_note, move_note, delete_note
contactssearch_contacts, get_contact
shortcutslist_shortcuts, run_shortcut
spotlightsearch_files
systemget_clipboard, set_clipboard, notify, open
always ondoctor

Install

You need macOS 14 or newer. For the npm route you also need Node 18 or newer.

Claude Code

claude mcp add applesauce -- npx -y applesauce

Claude desktop with npx

Open ~/Library/Application Support/Claude/claude_desktop_config.json and add this:

{
  "mcpServers": {
    "applesauce": {
      "command": "npx",
      "args": ["-y", "applesauce"]
    }
  }
}

Restart Claude desktop. To add a flag, put it in args, for example ["-y", "applesauce", "--read-only"].

Claude desktop with the .mcpb bundle

  1. Download applesauce-<version>.mcpb from the GitHub releases page.
  2. Double-click the file. Claude desktop opens an install dialog.
  3. Click Install. The dialog has three settings: read-only mode, only these modules, turn off these modules.

Any other MCP client

Run npx -y applesauce. It speaks MCP on stdin and stdout.

Flags and environment variables

applesauce [serve] [options]   run the MCP server (default)
applesauce doctor [options]    show the state of each macOS permission and how to fix it
applesauce --version
applesauce --help
FlagEnvironment variableMeaning
--modules a,bAPPLESAUCE_MODULESTurn on only these modules.
--disable a,bAPPLESAUCE_DISABLETurn off these modules.
--read-onlyAPPLESAUCE_READ_ONLY=1Hide every tool that changes data.

Module names: calendar, reminders, mail, notes, contacts, shortcuts, spotlight, system. A flag wins over its environment variable. An empty APPLESAUCE_MODULES means all modules.

Permissions

macOS keeps your data private. The first time a tool needs an app, macOS shows a prompt. Click Allow. The prompt names applesauce, not your terminal or Claude.

PermissionUsed byNotes
CalendarscalendarPrompt on the first calendar tool. Full access, so events can be read and changed.
RemindersremindersPrompt on the first reminders tool.
ContactscontactsPrompt on the first contacts tool.
Automation for MailmailPrompt on the first mail tool. If Mail is not running, applesauce opens it hidden in the background and leaves it open.
Automation for NotesnotesPrompt on the first notes tool. Notes must be running.
Full Disk Accessmail searchOptional. Gives fast search over all mail.

Spotlight, Shortcuts, the clipboard and open need no permission of their own. The first notify asks to show notifications. Until you allow it, notifications still appear, with the Script Editor icon. After that they show the applesauce icon.

Full Disk Access for fast Mail search

Without it, search_mail still works. It is slower, needs a mailbox, and looks at a date range only. With it, applesauce reads the Mail index directly, read-only.

  1. Ask your assistant to run the doctor tool, or run npx -y applesauce doctor in a terminal. Copy the binary: path, up to and including applesauce.app.
  2. Open System Settings, Privacy & Security, Full Disk Access.
  3. Click +. Press Cmd+Shift+G and paste the path. Select applesauce.app and click Open.
  4. Restart your AI app.

Permissions reset after an update

applesauce has no paid Apple signing, only an ad-hoc signature. macOS ties a permission to the exact binary. After each update, macOS may ask again, and Full Disk Access must be added again. With npx, a new version is a new file, so the same applies.

After an update, ask your assistant to run the doctor tool, or run npx -y applesauce doctor. It shows each permission, its state, and the exact step that fixes it. If a permission shows as denied, open System Settings, Privacy & Security, find applesauce in the list, and turn it off and on again.

Safety

  • --read-only (or the read-only switch in the .mcpb dialog) hides every tool that changes data.
  • send_mail and reply send nothing unless the call has confirm: true. Without it they save a draft.
  • Tools that delete, send or move mail are marked destructiveHint: true. Most MCP clients ask you before they run them.
  • Tools that only read are marked readOnlyHint: true.
  • run_shortcut runs a shortcut, and a shortcut can do anything on your Mac. Turn off the shortcuts module if you do not want that.
  • Every call has a time limit (30 seconds, and 120 seconds for a permission prompt).
  • Attachments are saved only by get_mail_attachment and get_note_attachment. Both need confirm: true on every call, and --read-only hides them. A file is limited to 25 MB. It goes to ~/Library/Caches/applesauce/attachments (private to your user) and is deleted after 24 hours.
  • Contact notes are never returned.

What can be undone

ActionUndoGate
Delete a noteNotes keeps it in Recently Deleted for 30 days.none
Delete up to 10 emailsMail moves them to the Trash.none
Delete more than 10 emails, or move them to Trash or JunkMail moves them to the Trash or Junk.confirm: true
Delete emails that are already in the TrashNone. The delete is final.confirm: true
Delete an event or a reminderThe result has a full copy, so the assistant can create it again (with a new id).none
Delete all later occurrences of a recurring eventNone.confirm: true

Without confirm: true, a gated call changes nothing and says why. Your assistant can still pass confirm: true by itself, so --read-only is the only hard block.

Attachments

  • get_mail_attachment and get_note_attachment save one attachment as a file and return its absolute path.
  • Images (JPEG, PNG, GIF, WebP) are also returned as an image. HEIC is converted to JPEG. An image above 5 MB is scaled down for the result. The saved file stays as it is.
  • PDF, plain text, RTF, DOC and DOCX files are also returned as text, cut at 100000 characters. A PDF without text (a scan) returns the path only. Other types return the path only.
  • Mail attachments that Mail has not downloaded cannot be saved. Notes cannot save drawings, scans, tables and links. The call then fails with an error.
  • search_mail and flag_message know the seven flag colors: red, orange, yellow, green, blue, purple and gray.

Limits

  • macOS 14 or newer.
  • No paid Apple signing and no notarization. Permissions reset after an update (see above).
  • Locked notes are not read.
  • Notes must be running. Mail is different: when a Mail tool needs it, applesauce opens Mail hidden in the background and leaves it open.
  • The Intel slice is built but not tested on Intel hardware.

Linux and Docker

applesauce needs macOS. The Dockerfile builds a Linux image for MCP directories that check servers in Docker. In that image applesauce starts and lists all its tools, and every tool call answers UNSUPPORTED_PLATFORM. doctor reports each permission as unsupported.

Build from source

You need Xcode with Swift 6.1 or newer.

swift build
swift test
scripts/sign.sh .build/debug/applesauce   # needed for macOS to show permission prompts

Release build and packages:

scripts/build-universal.sh   # dist/applesauce, arm64 + x86_64, ad-hoc signed
scripts/pack-npm.sh          # dist/applesauce-<version>.tgz
scripts/pack-mcpb.sh         # dist/applesauce-<version>.mcpb
scripts/version.sh --check   # all version numbers agree

The version lives in Sources/AppleSauceCore/Version.swift. Support/Info.plist, npm/package.json and mcpb/manifest.json must match it.

Credits

  • The self-disclaim pattern, which makes the binary own its permission prompts, comes from apple-reminders-mcp (source) by high5 ventures (MIT).
  • Built on the MCP Swift SDK.

License

MIT. See LICENSE.

NPM
applesauce
Install Command
npm install applesauce