convez.ai
MCP ServerAutomaçãoIntermediário
hassanzouhar

Apple MCP Server

hassanzouhar/apple-mcp-server

Acesse Calendar, Reminders, Contacts e Mail via IA no macOS

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta uma IA aos aplicativos nativos do macOS — Calendário, Lembretes, Contatos e Mail — via JXA (JavaScript for Automation). Executa localmente sem dependências externas, oferecendo 29 ferramentas para automação completa da produtividade pessoal.

Instalação

$npx convez-ai hassanzouhar/apple-mcp-server

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
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de agendamentos e consultas de calendário via conversa natural
  • Gerenciamento programático de lembretes e listas de tarefas
  • Busca e manipulação de contatos integrada com IA
  • Composição e envio de mensagens de email controlados por agente

Veredito

Implementação sólida e bem estruturada de MCP para ecossistema Apple. Cobre as aplicações essenciais de produtividade do macOS com granularidade apropriada (29 ferramentas). Adequado para quem precisa integrar IA com fluxos pessoais no macOS; requer Node.js 18+ e perms de segurança.

README

A tradução para o português deste README ainda está na fila.

apple-mcp-server

A Model Context Protocol server that connects an LLM to the four core Apple personal apps on macOS — Calendar, Reminders, Contacts, and Mail — via the JavaScript for Automation (JXA) bridge.

  • Transport: stdio (local-only)
  • Platform: macOS (Darwin) — this server uses /usr/bin/osascript and will refuse to start on any other OS
  • Stack: Node.js 18+, TypeScript, MCP TypeScript SDK, Zod
  • External services: none — everything runs locally against the native macOS apps

Tools (29)

Calendar (7)

ToolDescription
apple_list_calendarsEnumerate every calendar (local, iCloud, Google, Exchange…)
apple_list_eventsList events in a date range, optionally filtered by calendar
apple_search_eventsSubstring search across summary / location / description
apple_get_eventFetch one event by UID
apple_create_eventCreate a new event
apple_update_eventPatch any subset of event fields
apple_delete_eventDelete an event

Reminders (8)

ToolDescription
apple_list_reminder_listsEnumerate every reminders list
apple_list_remindersList reminders with filters (list, completed, due-date window)
apple_search_remindersSubstring search across name / body
apple_create_reminderCreate a reminder (with optional due date, remind-me, priority, flag)
apple_update_reminderPatch reminder fields
apple_complete_reminderToggle the completed flag
apple_delete_reminderDelete a reminder
apple_create_reminder_listCreate a new list

Contacts (5)

ToolDescription
apple_search_contactsSubstring search across name / org / email / phone
apple_get_contactFetch one contact by UID
apple_create_contactCreate a contact with emails and phones
apple_update_contactPatch top-level fields
apple_delete_contactDelete a contact

Mail (9)

ToolDescription
apple_list_mail_accountsEnumerate every Mail.app account
apple_list_mailboxesList mailboxes, optionally per account
apple_list_messagesList recent messages in a mailbox (unread filter, date window)
apple_search_messagesSubstring search across subject / sender
apple_get_messageFetch a full message body
apple_create_draftOpen a draft in Mail.app (NOT sent)
apple_send_messageSend a message immediately (requires confirm: true)
apple_mark_messageMark read / unread
apple_delete_messageMove to Trash (requires confirm: true)

Install & build

git clone <this-repo> apple-mcp-server
cd apple-mcp-server
npm install
npm run build

The compiled entry point is dist/index.js.

Run

node /absolute/path/to/apple-mcp-server/dist/index.js

The server speaks MCP over stdio; you normally don't invoke it directly — point your MCP client at it (see below).

Wire it up

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "apple": {
      "command": "node",
      "args": ["/absolute/path/to/apple-mcp-server/dist/index.js"]
    }
  }
}

Restart Claude Desktop. The first time the LLM calls a tool, macOS will prompt you to grant the host process (Claude Desktop) permission to control Calendar / Reminders / Contacts / Mail.

Claude Code / other MCP clients

claude mcp add apple node /absolute/path/to/apple-mcp-server/dist/index.js

macOS permissions

Each of the four apps gates AppleScript access behind a separate System Settings entry. Approve them up front to avoid mid-conversation prompts:

Need access toWhere to grant
Calendar.appSystem Settings → Privacy & Security → Automation → enable the host app under "Calendar"
Reminders.appSystem Settings → Privacy & Security → Reminders → add the host app
Contacts.appSystem Settings → Privacy & Security → Contacts → add the host app
Mail.appSystem Settings → Privacy & Security → Automation → enable the host app under "Mail"

If a tool returns Error: macOS denied access. Grant the host app …, that's the fix.

Design notes

  • JXA, not classic AppleScript. Every script is JavaScript — easier to interpolate user data safely and JSON-stringify return values.
  • No shell quoting. Scripts are passed to osascript over stdin. User input rides in a single argv slot as JSON; the wrapper inside runJxa parses it back into INPUT.
  • Each script is wrapped in a try/catch that returns {__ok, value | error} so errors surface cleanly as MCP tool errors with actionable hints (we detect the macOS "not authorized" family of errors and translate them).
  • Per-call timeouts. Mail can be slow on huge mailboxes; it gets a 60 s budget. Everything else uses 30 s.
  • whose() is unreliable on some Calendar / Mail collections — we use it where it helps and fall back to in-JS filtering everywhere else.
  • Destructive ops are explicit. apple_send_message and apple_delete_message both require confirm: true to be set by the agent.
  • All read tools return both Markdown and JSON. Pass response_format: "json" for programmatic processing.

License

MIT

Ver o original no GitHub

Bom para

Relacionados