Seven macOS apps your assistant can actually reach.

One string, wherever you keep it

The same spelling works in an MCP client's env block and in a shell: tool=class[+class], comma separated, with * for the tools you did not name.

A policy narrows only the tools it names. Without a *, every tool you did not mention keeps every operation — so PYAPPLE_PERMS="mail=read" is a read-only mail tool and six untouched ones. That is deliberate: saying something about mail is not saying anything about your calendar, and a parser that disarmed the calendar anyway would be removing a capability you never asked it to remove. It is also the most misread line on this page, reported twice as a leak. *=read narrows the rest; *=none removes it. pyapple perms names the tools a policy left alone rather than leaving you to infer them.

{
  "mcpServers": {
    "pyapple": {
      "command": "pyapple-mcp",
      "env": {
        "PYAPPLE_PERMS": "mail=read+draft,calendar=all,messages=read,*=read"
      }
    }
  }
}

That policy leaves 37 of the 65 operations. The assistant can read and compose mail — including answering it — but has no way to post any of it, has the calendar in full, can read Messages and nothing else, and keeps only the reads everywhere it was not named. PYAPPLE_READ_ONLY=1 is still here, as the documented shorthand for *=read.

It can only take away

--perms narrows a single invocation of the command-line tool that ships in the same package, and it intersects rather than replaces: nothing you type at a shell can restore what an MCP configuration took away. If it could, the variable would be a suggestion.

A policy string that cannot be parsed stops the program, naming the token it choked on. There is no “could not understand, carrying on” path, because a policy that fails open sends the email.

It stops it as bad input — exit 2, the same status as a bad command line, because the operation never started — and the message says which of the two inputs was wrong rather than leaving you to guess between a variable somebody set months ago and the flag you just typed: usage: PYAPPLE_PERMS: 'mail@read' is not 'tool=class[+class…]'. That holds on every entry point, including pyapple perms itself, which is the command you would run to find out. The MCP server refuses to start for the same reason and says so on stderr, where a client's log picks it up: a server that is simply missing is worth looking for in its env block.

Both settings apply through the same intersection, so PYAPPLE_READ_ONLY=1 beside PYAPPLE_PERMS="mail=send" yields no mail send, whichever order they are read in.

What each tool loses to *=read

Struck from the operation enum, per tool:

calendar

11 → 6

create, reschedule, alarms, move, delete

reminders

8 → 4

create, update, complete, delete

contacts

6 → 2

add, addTo, rename, delete

maps

7 → 3

save, pin, createGuide, addToGuide

notes

13 → 4

create, append, rename, replace, setBody, folderCreate, folderRename, folderDelete, delete

mail

13 → 7

send, draft, reply, replyDraft, open, markRead

messages

7 → 4

send, schedule, open

all seven

65 → 30

Every tool keeps the operations that only look.

Three of the operations struck here — save, createGuide and addToGuide — cannot be performed at all, on any grant. They stay on the surface so that a model asking for a favourite is told why rather than left to invent a route; and listGuides, which is the fourth of those and survives *=read, refuses too.

Absent, not refused

The mechanism is unchanged from the read-only switch, and it is still the point. Forbidden operations are not declined when they are called — they are gone from the operation enum in the tool definition the model reads, so there is no way to express the request at all.

A refusal is something to argue with. A missing enum member is not. And when an agent harness spawns this server directly, the surrounding application never sees the tool calls, so there is nowhere else the rule could have been enforced. The same applies to an operation nobody classified: it raises rather than defaulting to a class that happened to be convenient.

The permission got smaller, not different

This is the part worth being explicit about, because the usual shape of such a move is a trade. CNSaveRequest and EventKit writes are gated by the same privacy grant the reads already held — Contacts, Calendars, Reminders. An Apple Event needs a separate “control this app” Automation grant on top.

So somebody who never asks for an open now never answers an Automation prompt for Calendar, Reminders or Contacts at all. Nothing was given up to get that: the framework route is also the one that can tell you an event does not exist in 0.006s rather than 60.06s, and that can delete the fourth occurrence of a series instead of the first.

Checks assert the property rather than the symptom: contacts.py has no applescript name in it at all, so there is no handle left to reach the runner through, and mail's reads were proven against the real store with a runner that raises on any Apple Event. A window count is not something a check can see; an absent import is.

maps pays nothing, and reaches the network

MapKit asks for no privacy grant whatsoever, so maps search and maps directions are the only operations here that need nothing at all. Search went 2.68s → 0.72s, a route lookup 2.23s → 0.12–0.46s, and no window appears — verified by quitting Maps, running a search and three route lookups, and confirming the app was still not running.

It is also the one thing in this package that leaves your Mac other than sending. The remaining latency is a round trip to Apple's geocoder, not Apple Events. And there is no current location — a process that is not a bundled app cannot hold the Location Services grant — so directions always needs an origin, and “from here” is something the caller has to supply.

A window, once opened, is a one-way door

Measured on three apps, and it is why every operation that can show something has show off by default. close window 1 on Maps blocks until the Apple Event times out — error -1712, roughly two minutes — and leaves the window exactly where it was. Mail's compose window resists closing by reference, by index and by id, and hiding and deleting the outgoing message besides; every attempt returns without error and changes nothing.

Reminders is the one exception: its window does close. Everywhere else, opening a window commits the person at the keyboard to dismissing it by hand, which is not a decision an assistant should be making for them.

notes cannot follow, and that is permanent

There is no framework API for Apple Notes. Not a slower one, not a private one — none. AppleScript is the only route in, so notes keeps its Automation grant and will keep it.

What that route costs is visible in the reads. Notes' body is HTML, and on a 59-note store it runs to 13,790,681 characters where the text is 14,463 — a 953× amplification, almost all of it base64 image payloads, sent across the Apple Event boundary and then thrown away by a regular expression. It made search wrong as well as slow: body contains "the" matched 37 of 59 notes against 8 for plaintext, the extra 29 matching inside image data.

messages schedule cannot work, so it refuses

Messages' scripting dictionary declares three commands and none of them takes a date. The words “schedule”, “later” and “delay” do not appear in it anywhere. The database has columns that look like a way in until you notice that all fifteen rows carrying one also carry a send error.

It refuses, and a check pins that it never quietly sends immediately instead — which is the failure that would actually hurt. It stays on the tool surface rather than being removed, because a model asked to send something at seven in the morning, finding no such operation, is likely to reach for send.

One contact card in nine cannot be written at all

20 of 179 real cards refuse every framework write with Cocoa error 134092 — 11.2%, and stable per card rather than intermittent: 5 of 5 attempts fail on an affected card, 0 of 5 on each control. Measured over the whole address book, one card at a time, each change applied and then restored to its exact recorded original.

Nothing the API exposes separates the two groups. Ruled out by testing rather than by assuming: the container, the fetch key set, staleness, unification, linked cards, images, and the kind of change. So it cannot be pre-flighted and retrying is pointless. The tools refuse and name the reason, including the fact that the Contacts app can still edit the card — because the framework's own message is “The operation couldn't be completed”, which invites a retry that will fail forever.

The one good property, verified: the failure is total, never partial. Every affected card was byte-identical afterwards.

A command that never ran, and the check that was content

mail search-bodies crashed on every invocation from a shell. The renderer takes two arguments and the command passed one, so it raised after doing all of the work and exited 1 — not “returns empty”, never ran. It was wired an hour before it shipped, and a model trying to build a timeline out of a mailbox filed two of its six complaints against it.

The reason it got through is the interesting half. The parity check between the two front ends compares operation names, and the name was right — so it was perfectly content with a command wired to a function it could not call. There is now a check that invokes all 24 leaf commands against a stub. It cannot catch a wrong query or a wrong script; it catches exactly this.

Two renderer bugs went the same way inside one hour: mail coverage read three keys the handler does not produce, so every row printed None, and then formatted a value already in percent as a percentage and printed 10000%. A stub that invents its own payload passes both. The check that catches them uses the handler's real key names.

Unknown is not failure

A 120-second sweep returned success: False with the messages already marked. Timeouts now carry a distinct outcome meaning unknown, possibly partial, and it is raised rather than returned — a key on a dictionary can be dropped by writing if not result["success"], which is the line that produced the false report.

It proved itself in the wild before the release shipped. A send attempted while the machine sat at load average 321 was cut off, and reported that the outcome was unknown and that Sent should be checked before retrying. Sent showed nothing had gone, so the retry was safe — which is exactly the decision success: False makes impossible.

Scope is a requirement, not an optimisation

whose read status is false over a 45,000-message Gmail All Mail does not finish. Scoped to a single mailbox, the same query is 1.6s.

So an unscoped sweep is refused immediately, naming the mailboxes on this machine that you could scope it to. Offering a call that cannot work, and answering it two minutes later with an outcome nobody can report, is worse than saying no.

A verification here was wrong before it was right: the sent count was compared six seconds after a send and showed nothing, and fifteen seconds later it had moved. A check whose timing is wrong reports the same thing as a failure.

Two control characters cannot be stored, and it says so

U+001E and U+001F are how a refusal marks a parameter name, so that one sentence written once prints as --delete-notes at a shell and delete_notes to a model. Text arriving with them in it gets the same treatment. Measured: a reminder named shop ␞account␟ now was stored verbatim by EventKit and came back out as Created reminder 'shop --account now' — a flag this tool never offered, written by whoever typed the reminder.

They are now removed from every argument of every operation before anything is stored or matched. That was already happening on the AppleScript routes, as a side effect of there being no literal form for a control character — which is why notes and mail were incidentally safe and the EventKit, Contacts and MapKit writes were not.

The second half is that it is no longer silent. Storing text that differs from the text you sent and reporting plain success is the same fault as a truncated read that does not mention it: the write goes through, and the answer carries a count of what was removed and from which parameter — on stderr for a shell, in removed_control_characters under --json, and appended to the text an MCP client receives. Nothing else is touched; quotes, backslashes, emoji and bidirectional marks are stored exactly as sent.

Observed, and not a defect here

At that same load average of 321, every Apple Events path became unusable — Mail sat at 0% CPU in a runnable state, starved rather than broken — while the reads that go straight to the local index were unaffected, answering in 0.07s to 0.49s throughout.

Which is the three-routes picture from the top of this page, showing up as latency instead of as a permission dialog.

Local checkout

$ git clone https://github.com/54yyyu/pyapple-mcp.git
$ cd pyapple-mcp
$ pip install -e ".[dev]"
$ python -m pyapple_mcp.server

Inspect and check

$ npx @modelcontextprotocol/inspector pyapple-mcp
$ pytest   # 840 checks

black, isort and mypy are configured in pyproject.toml and run over the same tree. A check here is not trusted until it has been made to fail — the line it covers is deleted, the suite is confirmed red, and the line is put back. Several rounds of that found checks that were green against the bug they were written for, which is a claim of coverage rather than coverage.