mac-mcp
DaniAkash/mac-mcp
Read-only MCP server for native macOS apps (Mail, Notes, Calendar, Reminders, Contacts, Messages, Spotlight).
Instalação
npx convez-ai DaniAkash/mac-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
mac-mcp
A read-only MCP server that exposes data from native macOS apps (Mail, Notes, Calendar, Reminders, Contacts, Messages, Spotlight) to AI agents over stdio.
Bootstrapped with Vite+ and Bun. Status: Mail domain shipping; other domains in the pipeline.
Status
| Domain | State |
|---|---|
| shipped (v0.1) | |
| Spotlight | shipped |
| Notes | planned |
| Calendar / Reminders | planned |
| Contacts | planned |
| Messages | planned |
The server is read-only by construction. There is no CLI flag, env var, or config key that enables writes. A regression test sweeps every JXA template for write-capable Apple Events phrases (set readStatus, move to, delete, send, etc.) and another sweeps every tool / domain module to ensure they only spawn read-only system commands (osascript, mdfind).
Requirements
- macOS 14 or newer (15+ unlocks Apple Mail category support)
- Bun 1.3+
- Full Disk Access granted to your terminal / MCP client (for reading Apple's local data stores)
- Automation permission for Mail.app (granted at first JXA call when listing accounts)
CLI
mac-mcp serve # start the MCP server over stdio (default)
mac-mcp init # write ~/.mac-mcp/config.toml template
mac-mcp doctor # probe macOS permissions, print a checklist
mac-mcp status # print per-domain index health as JSON
mac-mcp index # bulk-build domain indexes
mac-mcp rebuild --domain <name> # rebuild a single domain's index
Mail tools (v0.1)
Five read-only MCP tools, plus the index://status resource.
| Tool | What it does |
|---|---|
mail_list_accounts | List all Mail accounts with display names + UUIDs. |
mail_list_mailboxes | List mailboxes per account with current unread counts. |
mail_get_emails | Recency-sorted email list. Optional account, mailbox, category (primary/transactions/updates/promotions), filter (all/unread/flagged/today/last_7_days), before/after (YYYY-MM-DD), and group_by to bucket by unread state, category, or account. |
mail_get_email | Fetch a full email by Mail.app integer id with body, recipients, headers. |
mail_search | FTS5 BM25 search across subject/sender/body with scope, account, mailbox, category, and date filters. |
Apple Mail category awareness
Mail's built-in categorisation (Primary, Transactions, Updates, Promotions) ships natively on macOS 15+. The server probes the message_global_data.model_category column at startup and degrades cleanly to category-less output on older macOS. The category filter and group_by: "category" both honour this gracefully.
Local index
The Mail domain maintains a SQLite + FTS5 index at ~/.mac-mcp/mail.db:
- WAL mode,
synchronous=NORMAL, denormalisedis_unread/is_flaggedcolumns for indexed sorts. - Disk-first state-reconciliation sync (NEW / DELETED / MOVED diffs in pure SQL).
- Background sync every 5 minutes by default (configurable).
- Dead-letter queue surfaces parse failures via
index://status.
Spotlight tool
One read-only tool: spotlight_search.
| Input | Type | Default | Notes |
|---|---|---|---|
query | string | required | Plain text or full mdfind metadata query syntax (kMDItemContentType == "public.image"). |
path | string | none | Restrict to this directory tree. Must resolve under $HOME. |
kind | "file" | "folder" | "any" | "any" | Post-filter on filesystem entry kind. |
limit | number | 25 | Hard cap 100. |
The macOS Spotlight index (mds) is already maintained by the OS; we never build our own. Subprocess runs mdfind with a 5-second per-call timeout; truncated indicates more matches existed beyond the limit.
MCP client config
{
"mcpServers": {
"mac": {
"command": "bunx",
"args": ["-y", "github:DaniAkash/mac-mcp"]
}
}
}
Run mac-mcp doctor after install to verify permissions.
Development
bun install # install dependencies
bun test # unit + integration tests (CI-safe; e2e tests skip themselves)
bun run test:e2e # live end-to-end tests; requires macOS + FDA + Mail.app data
bun run check # lint + format + fallow code-quality, in parallel
bun run lint # vp lint (oxlint with full TS typecheck)
bun run fmt # vp fmt --check
bun run fmt:fix
bun run build # vp pack
End-to-end tests
tests/e2e/ contains tests that hit the real Mail.app + Envelope Index on the local machine. They require Full Disk Access and a configured Mail account, so they only run when MAC_MCP_E2E=1 is set. CI never sets this env var; the tests skip cleanly on every CI run.
Coverage includes the five Mail tools called directly against the live data (sort order, unread / category / account grouping, multi-account filter, get-email round-trip) plus a full MCP stdio round-trip that spawns the actual mac-mcp serve binary and drives it as a real MCP client over JSON-RPC.
# Grant Full Disk Access to your terminal first.
bun run test:e2e
License
MIT