Metadata-Version: 2.5
Name: macos-apps-mcp
Version: 0.15.1
Summary: One consolidated MCP server for native macOS apps (Calendar, Reminders, Mail, ...).
Project-URL: Homepage, https://github.com/elfensky/macos-apps-mcp
Project-URL: Repository, https://github.com/elfensky/macos-apps-mcp
Project-URL: Issues, https://github.com/elfensky/macos-apps-mcp/issues
Project-URL: Changelog, https://github.com/elfensky/macos-apps-mcp/blob/main/CHANGELOG.md
Author-email: Andrei Lavrenov <andrei@lav.ren>
License-Expression: MIT
License-File: LICENSE
Keywords: apple,calendar,eventkit,macos,mcp,model-context-protocol,reminders
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: anyio>=4
Requires-Dist: cryptography<49; sys_platform == 'darwin' and platform_machine == 'x86_64'
Requires-Dist: fastmcp<4,>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.26
Requires-Dist: osxphotos<0.78,>=0.77.2
Requires-Dist: pyobjc-framework-cocoa>=10.0
Requires-Dist: pyobjc-framework-eventkit>=10.0
Requires-Dist: pyobjc-framework-servicemanagement>=10.0
Requires-Dist: pyobjc-framework-uniformtypeidentifiers>=10.0
Requires-Dist: starlette>=0.48
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# macos-apps-mcp
<!-- mcp-name: io.github.elfensky/macos-apps-mcp -->
<img alt="macos-apps-mcp logo" src="https://raw.githubusercontent.com/elfensky/macos-apps-mcp/develop/docs/images/logo.png" width="96" align="right">

One local [MCP](https://modelcontextprotocol.io) server for Mail, Calendar, Reminders, Notes,
Messages, Contacts, Photos, Safari, Music and Shortcuts on macOS. Searches and lists return pointers: an
id, a one-line summary and a link that opens the item in its app. Bodies are a separate, capped fetch.
Writes are tiered and audited; deletes, moves and sends preview first. macOS only. Python + [FastMCP](https://github.com/PrefectHQ/fastmcp) + [uv](https://docs.astral.sh/uv/). See
[DESIGN.md](https://github.com/elfensky/macos-apps-mcp/blob/develop/DESIGN.md) and [CHANGELOG.md](https://github.com/elfensky/macos-apps-mcp/blob/develop/CHANGELOG.md).

## What you can ask

- "What is on my calendar this week? When am I free on Thursday afternoon?" <br><sub>`events`, `free_busy`</sub>
- "Which emails need a reply? Draft a reply to the first one." <br><sub>`mail_needs_response`, `mail_reply`. The reply opens as a draft in Mail. It is not sent.</sub>
- "Move the newsletters in my inbox to Archive. Show me first." <br><sub>`mail_search`, `move_mail`, `mail_undo`. The move previews by default. `mail_undo` reverses it, within the known limits below.</sub>

## Safety and privacy

- **Local.** No telemetry, and no network requests of its own: only a local unix socket (shim to daemon) and the
  dashboard on 127.0.0.1. Three tools reach past the Mac through the apps, when called: the send tools (off by
  default) send through Mail, `safari_open` opens a page, and `run_shortcut` runs a Shortcut that can call the web.
- **Three tiers.** Read, write and outbound. Send tools are absent until you enable them per app:
  `macos-apps-mcp allow-send mail` (daemon) or `MACOS_APPS_ALLOW_SEND=mail` (stdio). `MACOS_APPS_READ_ONLY=1`
  registers reads only and wins over both.
- **Dry run first.** `dry_run` defaults to true for `delete_draft`, `move_mail`, `trash_mail`, `mail_undo`,
  `send_mail`, `reply_all`, `forward_mail`, `delete_reminder`, `delete_event`, `delete_note` and `update_note`.
  Other writes act when called. `mail_reply` opens a draft only.
- **Audit log.** Every write goes to `~/.local/state/macos-apps-mcp/audit.jsonl` (under `$XDG_STATE_HOME` when set).
  An update or delete by id also records the item as it was. The `audit` tool reads the log back.
- **Mail recovery.** Before a Mail move or delete, each message is copied as `.eml` under
  `~/.local/state/macos-apps-mcp/backup/mail/`. `mail_undo` reverses the batch. No tool empties the Trash.
- **Known limits.** A message Mail downloaded only in part is backed up without its attachments. Moves and trashes
  through a Gmail label folder are refused, because Gmail reverts them about 2 minutes later. `sent: true` means
  Mail accepted the message, not that it was delivered. [All Mail facts](https://github.com/elfensky/macos-apps-mcp/blob/develop/docs/mail-applescript-facts.md).
- **Dashboard.** Under the signed `.app` daemon, a local page (127.0.0.1 only) shows every write, what it changed,
  and the backup behind each Mail batch. Invented data below:

<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfensky/macos-apps-mcp/develop/docs/images/dashboard-batch-dark.png"><img alt="The dashboard: three newsletters moved to Archive, each one backed up, and the prompt that undoes the batch" src="https://raw.githubusercontent.com/elfensky/macos-apps-mcp/develop/docs/images/dashboard-batch.png" width="800"></picture>

## First 5 minutes

Requires macOS, Python ≥ 3.12 and [uv](https://docs.astral.sh/uv/). uv provides `uvx`. The package is on PyPI. Point your MCP client at `uvx`. It fetches the package and runs it, so there is no clone and no venv path:

```json
{
  "mcpServers": {
    "macos-apps": {
      "command": "uvx",
      "args": ["macos-apps-mcp"]
    }
  }
}
```

If Claude Desktop cannot find `uvx`, set `"command"` to its full path: run `which uvx` in Terminal (a default uv install prints `/Users/you/.local/bin/uvx`).

For Claude Code:

```sh
claude mcp add macos-apps --scope user -- uvx macos-apps-mcp
```

Or, instead of `claude mcp add`, install the Claude Code plugin. It starts the same server and adds a skill
that teaches the dry-run workflow. In Claude Code, run `/plugin marketplace add elfensky/macos-apps-mcp`, then
`/plugin install macos-apps@macos-apps-mcp`.

The CLI commands further down (`allow-send`, `dedupe-mail`) run the same way: `uvx macos-apps-mcp allow-send`.

**Run `doctor` first.** The `doctor` tool reports what is granted and opens no dialog (Automation shows `unprobed`). `doctor(request=True)`, with you at the screen, opens the EventKit and Automation dialogs. The server needs:

- **EventKit**: Calendar and Reminders.
- **Automation**, one dialog per app: Mail, Notes, Contacts, Safari, Messages, Music.
- **Full Disk Access** (optional, no dialog: turn it on in System Settings → Privacy & Security → Full Disk Access, for the app that starts the server): Messages content, Photos, Mail's index reads, reminder tags and subtasks, and the fast Notes path. Without it, Notes and some Mail reads use a slower path. The rest return an error or a `coverage` note.

Under stdio, macOS gives each grant to the app that starts the server (Claude Desktop, Terminal, VS Code), so each client needs its own. The signed `.app` daemon holds one set for all: [docs/DAEMON.md](https://github.com/elfensky/macos-apps-mcp/blob/develop/docs/DAEMON.md).

Load only the apps you use. `MACOS_APPS_ADAPTERS_OFF=photos,music` registers no tools for those apps, so your client holds fewer tools in its context. Under the daemon, see [turn adapters off](https://github.com/elfensky/macos-apps-mcp/blob/develop/docs/DAEMON.md#6-turn-adapters-off-under-the-daemon).

**From source (development):** use this path to work on the server itself.

```sh
git clone https://github.com/elfensky/macos-apps-mcp && cd macos-apps-mcp
uv sync
```

Then point your MCP client at the project's own venv python — deterministic, and it carries the locked PyObjC wheels:

```json
{
  "mcpServers": {
    "macos-apps": {
      "command": "/absolute/path/to/macos-apps-mcp/.venv/bin/python",
      "args": ["-m", "macos_apps_mcp"]
    }
  }
}
```

## Why not apple-mcp?

[apple-mcp](https://github.com/supermemoryai/apple-mcp) by Dhravya Shah pioneered one MCP server for all Apple apps. It is
now archived. It returned full note and email bodies inline. This server returns pointers, fetches bodies only on
request, and gates every write by tier. See [CREDITS.md](https://github.com/elfensky/macos-apps-mcp/blob/develop/CREDITS.md).

Something broke? Run `doctor` and paste its output into a [GitHub issue](https://github.com/elfensky/macos-apps-mcp/issues). The report shows process paths, so check them before you post.

## Tools

Reads return pointers; results are capped per adapter. Bodies/content are a separate bounded
fetch. Writes/actions are skipped entirely when `MACOS_APPS_READ_ONLY` is set (see below).

### Calendar & Reminders — read/write (EventKit)

| Tool | Args | Notes |
|------|------|-------|
| `events` | `when` = `today` \| `week` \| `YYYY-MM-DD` | list events as pointers |
| `free_busy` | `start`, `end` (ISO), optional `calendars` ids | merged busy intervals + free gaps in the window; no event details |
| `reminders` | `due` = `today` \| `overdue` \| `this-week` \| a list name | list reminders as `{results, coverage?}`; each result carries `folder`, `tags` and `parent` (read-only; needs EventKit and Full Disk Access) |
| `calendars` / `reminder_lists` | — | containers (id + name) to target writes |
| `create_event` / `update_event` | title, start, end (ISO), calendar, location, notes, `all_day`, `recurrence`, `alarms` (minutes before the start, at most 5; all-day: from local midnight, `-540` = 09:00 on the day) | `update` is a full replace by id, except `alarms`: omitted keeps the event's alarms, `[]` removes them |
| `delete_event` | id, `span`, `dry_run` | `dry_run` previews without deleting; a real delete is verified gone (the occurrence, not the series) |
| `create_reminder` / `update_reminder` | title, due, list_name, notes, `priority` (0–9), start, `recurrence` | `update` is a full replace by id |
| `create_reminder_list` | name | new list on the default account; an exact duplicate name is refused |
| `complete_reminder` | id | marks complete; completing a parent lists the subtasks it leaves open under `subtasks`; refused, changing nothing, when the Reminders store cannot be read (needs EventKit and Full Disk Access) |
| `delete_reminder` | id, `dry_run` (default **true**), `with_subtasks` | deletes by id and proves it gone; a parent with subtasks is refused unless `with_subtasks=true`, since deleting it deletes them too (needs EventKit and Full Disk Access) |

Event and reminder pointers carry `folder` = the calendar or list id, which
`free_busy(calendars=…)` and the write tools (`calendar=`, `list_name=`) take.

Reminder **tags** and **subtasks** (`tags`, `parent` = the parent's id) are read from the
Reminders store, read-only, and need Full Disk Access. When that store cannot be read, the
reminders still come back and `coverage` says why. No public API writes a tag or nests a
reminder, so no tool here does.

A write targets its container by **name or `Pointer.id`**; an ambiguous name raises rather than
guessing. **Recurrence** is an RFC 5545 `RRULE`: `FREQ`, `INTERVAL`, `COUNT`, `UNTIL`, `BYDAY` (with
ordinals such as `2TU` or `-1FR` for monthly and yearly rules), `BYMONTHDAY`, `BYMONTH`,
`BYYEARDAY` and `BYSETPOS`, e.g. `FREQ=MONTHLY;BYDAY=2TU;COUNT=6`. A recurring reminder needs a
due date. `BYWEEKNO`, `BYHOUR`, `BYMINUTE`, `BYSECOND` and `WKST` are refused by name (EventKit
saves `BYWEEKNO` but expands only the first date), and so is any value out of range or any
combination RFC 5545 forbids; each part is checked again after the write. A start date that
does not match its rule is accepted — RFC 5545 counts it as the first occurrence — and the
event result says that the first occurrence is an extra one.

### Mail — id-first read + draft-and-open (Automation)

Sending is **off by default**: reads, `create_draft`, and `mail_reply` never send — they
open a compose window for you to review. Outbound (`send_mail`, `reply_all`,
`forward_mail`) exists but only runs when the operator opts in via
`MACOS_APPS_ALLOW_SEND`, and `dry_run` still defaults to `True` even then.

| Tool | Args | Notes |
|------|------|-------|
| `mail` | subject-OR-sender substring | inbox matches; id = stable RFC822 message-id, `message://` deeplink |
| `mail_body` | id, mailbox | one message's plaintext, bounded + truncation-marked; `mailbox` is the `folder` value from a `mail_search` result passed back **verbatim** (or a canonical name) — **any** mailbox, not just the inbox |
| `mail_search` | subject, from_, to, mailbox, account, since, until, unread, flagged, has_attachments, body, limit | indexed search via Envelope Index (at rest — no Mail launch **unless** `account=` is a display name, which is resolved through Mail; a UUID stays pure sqlite, an unknown name raises); one result per message (INBOX **preferred**); `has_attachments` excludes inline images; `body` best-effort (indexed only) |
| `mail_index_bodies` | rebuild | builds/refreshes opt-in **FTS body index** from `.emlx` at rest; resumable, size-capped; skips not-yet-downloaded (partial coverage by design) |
| `mail_thread` | id, limit (default 100) | whole conversation, oldest-first, **includes your sent messages**; deduped; over `limit` **oldest dropped** (thread read for reply) |
| `mail_overview` | — | every mailbox with total + unread, unread-first; includes Junk/Trash/All Mail; counts live (stored counters go stale) and per distinct message; account **names** come from Mail (launches it), UUIDs stand in when it's unreachable; On My Mac always named |
| `mail_attachments` | mailbox (a search result's `folder`, verbatim — or `inbox`/`sent`/`drafts`/`trash`/`junk`), optional query | attachment name/size/downloaded per message; works on **Drafts** |
| `mail_needs_response` | — | inbox mail likely needing your reply, ranked with a `reason` (flagged / unread-direct / unanswered-direct); headers only, no bodies read |
| `mail_awaiting_reply` | `days` (1–365, default 3) | mail **you** sent ≥ `days` ago with no reply (real In-Reply-To/References threading), oldest first, reason `awaiting-reply` |
| `create_draft` | to, subject, body | opens a draft for review — **never sends**; returns a locator |
| `mail_reply` | message_id, mailbox, reply_body, `include_quote` | native threaded reply (sets In-Reply-To/References), quoted original, opens for review — **never sends** |
| `drafts` | — | list Mail drafts as pointers (id + subject — to recipient) |
| `delete_draft` | id, `dry_run` | delete one draft by message-id; `dry_run` previews |
| `create_mailbox` | name (`/` nests), account | creates the folder; missing parents auto-created. **No delete counterpart** — `delete <mailbox>` is not scriptable, so removing one is a Mail.app action. In a Gmail account the new folder is a label, which `move_mail` refuses |
| `move_mail` | ids (≤25), from_mailbox, to_mailbox, `dry_run` | file/archive/refile; every message backed up + logged **before** anything moves, so `mail_undo` puts it back. `dry_run` defaults to `True`. Cross-account moves leave exactly one copy. A Gmail label folder is refused at either end (a move out of a label leaves a copy), and so is a unified name as the source |
| `trash_mail` | ids (≤25), mailbox, `dry_run` | **soft delete, and the only delete there is** — Mail's `delete` moves to the account's Trash and nothing in its scripting dictionary erases from there. Undoable via `mail_undo`; emptying Trash is yours to do in Mail.app. `dry_run` defaults to `True` |
| `mail_undo` | receipt, `dry_run` | replay a `move_mail`/`trash_mail` receipt in reverse; the undo is itself backed up and undoable. A receipt into a Gmail label or a unified name is refused, with how to restore by hand |
| `update_mail_status` | ids (≤25), mailbox, `read`, `flagged`, `flag_color` | mark read/unread, flag (+colour). Re-issuing with the opposite value **is** the undo, so `dry_run` defaults to `False` |
| `mail_duplicates` | `limit` | **report only** — per-mailbox redundant-copy counts + worst offenders. Cleanup is the `dedupe-mail` CLI below; this tool cannot delete |
| `send_mail` | `to`, `subject`, `body`, `cc`, `bcc`, `html`, `from_address`, `dry_run` | **gated** by `MACOS_APPS_ALLOW_SEND`; `dry_run` defaults to `True` |
| `reply_all` | `message_id`, `mailbox`, `body`, `include_quote`, `dry_run` | **gated**; native threading headers |
| `forward_mail` | `message_id`, `mailbox`, `to`, `dry_run` | **gated**; original + attachments forwarded intact — no covering-note param (writing the body destroys both, device-verified) |

### Messages — content via chat.db (read-only; Full Disk Access)

| Tool | Args | Notes |
|------|------|-------|
| `messages_chats` | — | conversation list (id + name); no content, no FDA needed |
| `messages_search` | query, `limit` | search message **text** (decodes `attributedBody`), newest first |
| `messages_with` | contact (phone/email), `country`, `limit` | recent messages with one person; `country` = calling code or 2-letter region (locale default, never +1) |
| `message_body` | id | full text of one message by guid |

### Notes — NoteStore.sqlite reads + opt-in bodies

| Tool | Args | Notes |
|------|------|-------|
| `notes` | title, snippet or body words | `{results, truncated?, plane?, coverage?}` — matching notes (id + snippet), title/snippet hits first, then body-only hits; bodies are searched in memory on the Full Disk Access plane (locked notes skipped); body words split at spaces and punctuation only, so a word inside unspaced Chinese or Japanese text is found by title or snippet only; diacritic- & smart-punctuation-insensitive |
| `notes_all` | — | every live note (id + "Account / Folder" + snippet), Recently Deleted excluded |
| `note_bodies` | ids (≤ 50) | opt-in plaintext hydration → `[{id, body}]` |
| `create_note` | title, body, optional `folder` name | returns the **stable x-coredata id**; an unknown/ambiguous folder is refused, not guessed |
| `update_note` | id, title, body | full replace of title+body by id; the stable id is preserved and verified after write |
| `delete_note` | id, `expect_title`, `dry_run` | moves to Recently Deleted; `dry_run` previews |

### Other read-only context

| Tool | Args | Returns |
|------|------|---------|
| `contacts` | name substring | cards (name, org, first phone + email) |
| `photos` | search string | `{results, truncated?}` pointers (title · filename · date), newest first, at most 25; matches filename, title, description, keywords, place, people and labels. The id is the Photos uuid; the old `<UUID>/L0/001` id is still accepted |
| `photo_albums` | — | `{results, truncated?}` album pointers (id, `title (n photos)`, folder path), at most 100 |
| `photo_info` | photo id | dates, location, place, people, EXIF subset, pixel size, kind; never image bytes or thumbnails |
| `safari_tabs` | — | every open tab (url + title) |
| `shortcuts` | name substring (empty = all) | the user's Shortcuts; id = stable UUID, `shortcuts://` deeplink |
| `ping` / `now` / `doctor` | — (`doctor` takes optional `request=True` to trigger permission prompts) | health check / time / permission diagnostics |
| `audit` | optional `since` (ISO datetime) | recent write audit entries (newest first) — what macos-apps-mcp changed, with before/after pointers (enough to undo by hand) |
| `usage` | — | per-tool call counts + the never-used list, for pruning rarely-used tools |

### Actions (writes)

| Tool | Args | Notes |
|------|------|-------|
| `create_contact` | given_name, family_name, organization | |
| `run_shortcut` | name **or** id, optional `input_text` | runs a Shortcut; returns a bounded output snippet |
| `safari_open` | url | opens in a new tab; bare host → `https://`; only `http`/`https` allowed |
| `export_photo` | photo id, `dest_dir` inside the allowed root | writes the edited still (the original when there is no edit) as a new file, name `<original stem>_<id prefix>.<ext>`, never overwritten, capped at 250 MiB; a photo only in iCloud is `absent` (nothing is downloaded); videos refused, a Live Photo exports its still only; additive, audited |

### Read-only mode

Set `MACOS_APPS_READ_ONLY=1` (or `true` / `yes`) to register reads only — every write and action
tool is skipped, a safe-deploy guard. (Reads may still open apps / read local stores.)

### Turning adapters off

Set `MACOS_APPS_ADAPTERS_OFF=photos,music` (a comma list of adapter names) to register no tools
for those apps. Under the daemon, the file `~/.local/state/macos-apps-mcp/adapters_off` holds the
same list and takes effect after a restart. Details: [docs/DAEMON.md](docs/DAEMON.md#6-turn-adapters-off-under-the-daemon).

### Dashboard

Under the daemon, `http://127.0.0.1:47632` shows the audit trail, Health, the adapter switches,
usage and the Mail backups. Run `macos-apps-mcp dashboard` to open it with its page key. Details:
[docs/DAEMON.md](docs/DAEMON.md#7-the-localhost-dashboard). Both screenshots use invented data.

<img alt="One calendar edit in the dashboard: the old time struck through, the new time beside it, and the exact tool call the model made" src="https://raw.githubusercontent.com/elfensky/macos-apps-mcp/develop/docs/images/dashboard-diff.png" width="800">

<img alt="The adapter switches: each app with its permission, its tool count and how often it was called" src="https://raw.githubusercontent.com/elfensky/macos-apps-mcp/develop/docs/images/dashboard-adapters.png" width="800">

### Cleaning up duplicate mail

Mail accumulates redundant copies of the same message — a UI drag copies rather than moves, Gmail
shows one message under both a label and All Mail, migrations leave copies on two accounts. The
read tools already collapse them, so this is only about what is physically on the server. Ask a
session for `mail_duplicates()` to see the damage, then clean up in a terminal:

```sh
macos-apps-mcp dedupe-mail                       # preview every mailbox — changes nothing
macos-apps-mcp dedupe-mail --verbose             # also list the sets it will NOT touch
macos-apps-mcp dedupe-mail --execute --mailbox=<folder-url>   # do one mailbox for real
```

A **CLI command, not a tool**, for the same reason as `allow-send`: thousands of deletes against a
30-second-capped serialized worker is hours of work a human starts. It only collapses copies that
are **byte-identical** (size *and* date sent) — Mail gives no way to address one specific copy, so
the survivor is whichever one Mail leaves, and identical bytes are what make that safe. Sets that
differ are counted, left alone, and listed under `--verbose`.

Redundant copies go to **Trash**, in small batches, each its own `mail_undo` receipt. Emptying the
Trash is yours to do in Mail.app — nothing here can erase a message.

**It is slow: ~1 minute per duplicate set** against a real IMAP account (Mail's `whose` lookup scans
the whole mailbox), so a big folder is hours. Run it in a terminal you can leave, one mailbox at a
time. It is resumable — the plan is recomputed from Mail's index on every run, so interrupting it
costs nothing and re-running just finds less to do. A set Mail fails to delete is reported, not
retried silently.

### Outbound (send) mode

Sending is **off by default** — the server creates drafts and never sends. Turn it on with:

```sh
macos-apps-mcp allow-send mail    # or: messages / mail,messages / all / off
macos-apps-mcp allow-send         # print the current setting
```

That persists the opt-in and restarts the daemon so it re-registers (registration happens at
import, so a restart is unavoidable — reconnect your MCP client afterward). It is a **CLI
command, not a tool**: the gate is your consent, so the model can neither grant itself sending
nor restart the server out from under your session.

The same choice is available as `MACOS_APPS_ALLOW_SEND` in the environment, which is what a
stdio server reads (a set variable always wins over the persisted toggle):

| Value | Effect |
|---|---|
| unset (default) | no send tools are registered at all |
| `mail` | Mail outbound only (`send_mail`, `reply_all`, `forward_mail`) |
| `mail,messages` | named adapters (comma list) |
| `1` / `true` / `yes` / `all` | every adapter's outbound |

`MACOS_APPS_READ_ONLY` always wins: with both set, no send tools are registered.

Send tools take `dry_run`, which **defaults to `True`** — deliberately inverted from the
id-addressed deletes. A delete targets an item a read already returned; a send *constructs* its
recipient, and a wrong recipient is the failure that matters. The dry run makes no call into Mail
at all and reports the resolved envelope; pass `dry_run=False` to actually send. `reply_all` is
the one exception: its dry run reads (never sends) the original message's actual to/cc
recipients, because that's exactly the recipient set a caller can't predict.

A successful `send_mail` / `reply_all` / `forward_mail` result (`sent: True`) means Mail
**accepted** the message — not that it was delivered. Device-verified: a perfectly-formed message
can sit in Mail's Outbox undelivered for minutes after `send` returns, and a stranded
recipient-less message can jam the outbox so later, valid sends queue behind it and never leave.
Every result also reports `outbox_pending`, Mail's current outbox count; when it's greater than
zero the result carries a `note` explaining that delivery is not confirmed and to check Mail ▸
Outbox.

Run the `doctor` tool to check whether sending is actually enabled — `deployment.outbound` lists
every adapter currently send-enabled (`[]` if none), derived from the same registration logic
above rather than a re-read of the raw env var, so it can never disagree with what got registered;
`deployment.outbound_note` explains the state in prose.

**Under the daemon deployment**, setting `MACOS_APPS_ALLOW_SEND` in an MCP client's config is a
silent no-op: the client's `env` block reaches the shim, not the long-lived daemon process that
reads the variable at import time, and the shipped LaunchAgent plist ships no
`EnvironmentVariables` key. This is exactly why `allow-send` exists — it writes state the daemon
can read (`~/.local/state/macos-apps-mcp/allow_send`, home-pinned so the shell that writes it and
the launchd process that reads it always agree) and survives reboots, unlike `launchctl setenv`.
See [docs/DAEMON.md](docs/DAEMON.md) ("Outbound (send) mode under the daemon").

## Develop

```sh
uv sync
uv run pytest                   # unit tests (mock at the adapter boundary)
uv run pytest -m integration    # real macOS / EventKit / TCC — run manually, never in CI
uv run ruff check .             # lint (config in pyproject.toml)
uv run ruff format .            # format
uv run macos-apps-mcp                  # run the server (stdio)
```

ruff (lint + format, line-length 88) and pytest gate CI — full workflow in
[CONTRIBUTING.md](CONTRIBUTING.md).

## Prior art & credits

macos-apps-mcp builds on prior work — the Apple Mail MCP it draws from, the EventKit/Photos servers it
references, the project that pioneered the unified-Apple-MCP pattern, and FastMCP / PyObjC / the MCP
spec it depends on. See [CREDITS.md](CREDITS.md).
