convez.ai
MCP Server
DaniAkash

mac-mcp

DaniAkash/mac-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

Read-only MCP server for native macOS apps (Mail, Notes, Calendar, Reminders, Contacts, Messages, Spotlight).

Instalação

$npx convez-ai DaniAkash/mac-mcp

1 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

Estrelas
5
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

DomainState
Mailshipped (v0.1)
Spotlightshipped
Notesplanned
Calendar / Remindersplanned
Contactsplanned
Messagesplanned

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.

ToolWhat it does
mail_list_accountsList all Mail accounts with display names + UUIDs.
mail_list_mailboxesList mailboxes per account with current unread counts.
mail_get_emailsRecency-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_emailFetch a full email by Mail.app integer id with body, recipients, headers.
mail_searchFTS5 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, denormalised is_unread/is_flagged columns 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.

InputTypeDefaultNotes
querystringrequiredPlain text or full mdfind metadata query syntax (kMDItemContentType == "public.image").
pathstringnoneRestrict to this directory tree. Must resolve under $HOME.
kind"file" | "folder" | "any""any"Post-filter on filesystem entry kind.
limitnumber25Hard 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

Ver o original no GitHub

Relacionados