PyApple MCP Tools

There are two front ends over the same integrations: an MCP server for Claude Desktop and other MCP clients, andpyapple, a command line for driving the same ten tools from a shell. They share one permission policy, so what you allow in one you have allowed in both.

If you are an agent about to drive the CLI rather than a person reading about it,.claude/skills/pyapple/SKILL.mdin this repository is the operator guide: which call to make first, how to read the exit status, and which refusals to route around versus report.

# Install pyapple-mcp pip install pyapple-mcp # Run the setup helper to configure Claude Desktop pyapple-mcp-setup

- Find your pyapple-mcp installation
- Locate your Claude Desktop config file
- Automatically add the configuration
- Display helpful setup information

Configure Claude Desktopby editing~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "pyapple": { "command": "pyapple-mcp" } } }

Restart Claude Desktopto load the new configuration.

Nothing else is needed to use the CLI;pip install pyapple-mcpis the whole installation.

Through the MCP server you ask in plain language; through the CLI you type the operation. The first two headings below are the former, the third is the latter.

Can you send a message to my sister saying "Hello from Claude!"?

Find all notes about "AI research" and summarize them

Create a reminder to "Buy groceries" for tomorrow at 5pm

Get directions from "Apple Park" to "San Francisco Airport"

You can chain commands together for complex workflows:

"Find the email with the booking reference in it, and put the reference in my trip note"

The same operations are available without an MCP client at all:

pyapple messages conversations --query "book club" pyapple mail unread --limit 5 --since 2026-08-01 pyapple calendar free --from-date 2026-08-06 --to-date 2026-08-08 --duration 60 pyapple presence snapshot pyapple doctor report

Every one of these was measured against the real applications, and each is something you need to knowbeforerelying on a tool rather than after. They are not bugs waiting to be fixed; where a thing cannot be done, the operation still exists and refuses out loud, because an assistant that has no operation for what it was asked will reach for the nearest one that does exist.

Almost nothing launches an app any more — but Mail, Messages and Notes still do

Reminders, calendar and contactswritesmoved from Apple Events to EventKit andCNSaveRequest; maps search and directions moved to MapKit. Those four tools now need only the privacy grant their reads already held, and the separate"control Automation"grant they used to demand is gone. Verified with Calendar, Reminders and Maps all quit: listing calendars, listing reminder lists, finding free time, searching for a place and routing between two of them launched none of the three.

What still dispatches Apple Events, and therefore still launches its app and still needs Automation:

mail threadandmail attachmentsare on the index-and-filesystem side with the other reads: no Apple Event, Mail is not launched, and nothing is marked read.reminders listCreateandlistDeleteare EventKit like the rest of that tool.

shortcutsis a fourth route into macOS and the cheapest one here.It goes through/usr/bin/shortcuts, a plain subprocess. Measured against the binary Apple ships:codesign -d --entitlements -shows nocom.apple.security.automation.apple-events, andotool -Lfinds no AppleEvents and no Carbon — it reaches its daemon overmach-lookup.shortcuts listandshortcuts run <a name that does not exist>were both run with Shortcuts.app not running; neither prompted and neither started it.shortcuts openis the exception and puts the editor on screen, which is whatcalendar openandreminders opencost.

Two honest qualifications, because that is easy to over-read.Wepay no permission; theshortcutdoes — one whose actions touch Contacts or Photos raises those prompts against Shortcuts, and this package cannot enumerate what a shortcut will reach, so it cannot warn you either. And a shortcut containing an interactive action will put UI on screen and block until somebody answers, which is whyrunhas a timeout at all.

Notes is the exception that cannot be fixed.Notes ships no framework API at all, so AppleScript is the only route in and Notes.app launches for every operation including a search and includingfolders. That is a platform limit, not an omission.

mail accountscame off that list. It used to ask Mail whether each account was enabled; it now reads the same indexcoveragereads and reports what this Mac actually holds per account, which is the consequence a caller cares about where "disabled" was only a cause of it. It falls back to asking Mail only if the index names no accounts at all, which on a machine with mail means the read failed rather than that there are none.mail coverageandmail readMessagenever touch Mail either — index and filesystem only.

maps pinis the odd one out: it opens a Maps window, but throughopen(1)and amaps://URL rather than an Apple Event, so it needs no Automation grant. It opensbehindwhat you are working in unless you pass--show. The window cannot be closed again from here — measured,close window 1blocks until the Apple Event times out and leaves the window where it was — so a pin is a one-way door.

Notes editing refuses more than it accepts

Notes' HTML serialiser and its HTML parser do not agree, sothe body Notes hands you is not a body it will take back. Every edit here is a whole-body rewrite, because Notes offers nothing else, so a read-modify-write is destructive. Measured, writing a body back unchanged:

Soappend,rename,replaceandsetBodyrefuseany note carrying that content, name what it holds, and change nothing. There is deliberately no override flag: a flag saying "yes, lose the images" would be set by a model that has never seen the note, on behalf of someone who has, and the loss is invisible afterwards — the attachment does not go to the Trash, it is gone.

On the development machine 0 of 56 existing notes pass that gate— 40 carry an attachment, 36 an image, 19 a heading, 13 a link, and 6 are password protected. That is the honest number, and it is why the refusal is worth documenting rather than discovering. Notes this tool creates always pass, socreatethenappendworks as you would expect.

createanddeleteare unaffected by that gate: neither reads a body back.

createhas a refusal of its own, though.It used to make any folder it was handed, silently, so a misspelled folder name did not fail — it started a second folder and filed the note there, reporting success. It now refuses a folder that does not exist and names the ones that do.notes foldersis the listing that lets you check first, andnotes folder-createis how you make one on purpose; the tool's own default folder is the one exemption, since a caller that named no folder cannot be told the folder it did not ask for is missing.

The refusal is the right way round because of what it costs to be wrong either way. Refusing when a new folder was genuinely wanted costs one further call tofolder-create, immediately, with the error naming what the folder could have been. Creating on a typo costs a folder in your sidebar, and two more calls —notes moveto file the note where it belonged andfolder-deleteto remove what the typo made.

notes folder-deletedestroys what is in it

Every other delete in this package is recoverable from a Trash or a Recently Deleted. This one is not, and that is measured rather than assumed: a disposable folder holding two notes was deleted, the trash's own note count was3 before and 3 after, and a search ofevery note— which does reach the trash, since the same query found a trashed note by name in the same run — matched0of the two deleted bodies. The notes are gone, not filed away.

So the refusals are the feature, and there are four of them:

-

A folder holding notes is refusedunless you pass--delete-notes Nwith the folder'sexactcount.Nis re-checked against the live store, so a count that has moved since you read it refuses rather than proceeds. You cannot pass the flag without having counted first, and that interlock is the only thing between a mistyped folder name and an unrecoverable loss.

A folder with subfolders is refused outright, with no override at all. Deleting a container leaves the app in a state whereid ofthat container raises, and there is no argument that gets past this.

The trash and any account's default folder are refusedfor what they are. There is one of each per account and nothing here needs to remove them.

The result carriesmay_return: Truerather than a bare success, because a synced account may put the folder back. Measured on both account types on one machine: an Exchange folder was listed again inside 15 seconds and was still there five minutes later, and iCloud resurrection has been reproduced five times — but neither reproduces every time, which is why the caveat is unconditional rather than naming an account. The script re-queries after deleting and reports what it saw, so what you get is what the store said, not what the command intended.

The message says only what happened. Delete anemptyfolder and it warns that a synced account may restore it and stops there; the sentence about notes not being in Recently Deleted appears only when notes were actually destroyed, andnotes_recoverableisnullrather thanfalsewhen there were none to recover.

pyapple notes folders # read the count first pyapple notes folder-delete "Scratch" --delete-notes 2

Four of seven maps operations are permanently impossible

Maps.app shipsno scripting dictionary— there is no.sdefanywhere in it — and Favourites and Guides have no public API and no readable on-disk copy; the data is CloudKit-backed and opaque. Sosave,listGuides,createGuideandaddToGuidecannot be implemented at all.

They report failure and hand back a durablemaps.apple.comlink instead, which is the part you can actually keep: stored in a note or a reminder it survives and opens in Maps on every Apple device.

$ pyapple maps list-guides; echo $? failed: Apple Maps guides cannot be listed. macOS exposes no API for them and keeps no readable copy on disk — the data lives in iCloud in a private format. This is not an empty list of guides; it is no answer at all. Open Maps and look under Library to see them. 1

listGuidesin particular must never answer with an empty list: a store that cannot be read has to be distinguishable from a store with nothing in it.

There is also no current location.A non-bundled process cannot hold the Location Services grant, so "directions from here" has no answer anddirectionsalways needs an explicit--from.

A shortcut's actions cannot be read, which is whyrunis asend

/usr/bin/shortcutshas four subcommands —run,list,view,sign— and Apple's own help for the third reads"View a shortcut in Shortcuts."It opens the editor.There is no subcommand that describes what a shortcut does, soshortcuts describereportsactions: nullandactions_known: falseand says why, rather than returning an empty list. A shortcut that could not be described must not read as a shortcut that does nothing.

(~/Library/Shortcuts/Shortcuts.sqlitecarries aZACTIONSDESCRIPTIONcolumn, which is the obvious way round it. It was populated for2 of 7shortcuts on the library this was written against, so it is a cache and not a source: reading it would answer "what does this do" for some shortcuts and silently for none of the others. It is not read.)

That is also the whole argument forrunbeing classifiedsendrather thanwrite. An effect nobody can read has to be assumed to be the worst one it could have, and a shortcut can trivially send mail. The decisive part is what the alternative would do to a promise this package already makes:PYAPPLE_READ_ONLY=1is documented as=readand it is the flagship safety setting, and ifrunwere anything belowsendthat setting would permit arbitrary user code that can text a stranger. Classified too high it costs somebody an extra grant; classified too low it sends the email.

But that is a per-account setting, not a fact about Mail.Mail.sdefdeclaresmove deleted messages to trashon theaccountclass, and with it off a deleteerases. Nothing in the verb's name says so and the caller cannot see the setting, so the script reads it off the message's own accountbeforetouching anything and refuses when it is off, pointing atmoveinstead. The same refusal covers a message whose account could not be determined at all: an unverifiable claim of recoverability is not a weaker claim, it is a false one.

mail moveis the reversible neighbour and it refuses three things rather than guessing: a destination that names no mailbox (with the real ones listed — it will not create a mailbox out of a typo, which would sync a new folder to somebody's phone), a name that matches more than one (Senton a machine with three accounts is three mailboxes), and a destination it could notcheck*, since listing mailboxes is itself an Apple Event and an empty answer there means "Mail did not answer" rather than "there are none".

Whether an attachment is on this Mac is astat, and the answer is tri-state

Both attachment operations report presence by looking for the file, not by believing the database, and neither will report "not there" when it means "cannot say".

messages attachmentscarriesavailable_locally, and it has three values. Measured across 5,426 rows on a real store: 35 of the 5,404 that name a path have no file at that path, and two of those 35 carry the sametransfer_stateas the 5,365 that do — so the column cannot be trusted and presence is astat.Nonemeans no path was recorded at all, which is unknowable rather than false.

mail attachmentsreports names and sizes, andsizes are not in the index: theattachmentstable has four columns and none of them is a size, so a size can only come from the file. On the store measured, 2,755 of 8,101 indexed attachments — 34.0% — have their bytes on this Mac, the same splitcoveragereports for bodies.A size that is not known isnull, never0.A zero-byte attachment and one whose bytes were never downloaded are different facts,on_disksays which you have, and the note says how many of each.

Every mailsendleaves a copy in the sender's Drafts

Mail autosaves any outgoing message it can attribute to an account. Measured directly, by building a message that was never saved and never sent: it appeared in Drafts within 8 seconds and stayed.

This is known and not fixed.The copy appears asynchronously, so an in-script cleanup runs too early, and a later one would mean this package deleting from your Drafts by subject match. It is documented rather than papered over because the failure it causes is a person seeing the draft, concluding the mail never went, and sending it again.

mail searchBodiesis partial by construction, and the split is per account

Bodies are not in the Envelope Index, so a body search has to open.emlxfiles on disk — and those exist for only part of the store. On the development machine that is 14,532 files against 45,654 indexed rows, about 32%.