Apple Reminders

Um servidor para integração nativa com o Apple Reminders no macOS.

Documentação

Apple Events MCP Server

Um servidor Model Context Protocol (MCP) que fornece integração nativa com Apple Reminders e Calendar no macOS por meio do framework EventKit. Expõe lembretes, listas, subtarefas e eventos de calendário por meio de uma interface padronizada com operações CRUD completas.

O backend EventKit é o CLI Swift independente event, incluído como submódulo git e compilado em bin/event durante pnpm install — não é necessário brew install separado. Consulte docs/migration-to-event-cli.md para a troca de backend na v1.5.0 e a lista de campos de escrita ainda não expostos por event.

Recursos

CRUD completo para lembretes, subtarefas, listas de lembretes e eventos de calendário
Prioridade (alta/média/baixa/nenhuma), tags e subtarefas com acompanhamento de progresso
Filtros multicritério: conclusão, intervalo de datas de vencimento, prioridade, tags, busca de texto completo, recorrentes, por localização
Formatos de data flexíveis (YYYY-MM-DD, YYYY-MM-DD HH:mm:ss, ISO 8601) com reconhecimento de fuso horário
Integração nativa com macOS via EventKit — valores configurados em Reminders.app / Calendar.app são refletidos nas respostas de leitura
Descoberta e solicitação automática de permissões do macOS
Suporte completo a Unicode com validação abrangente de entrada

Pré-requisitos

Node.js 20 ou posterior
macOS (necessário para EventKit)
Xcode Command Line Tools (apenas ao compilar a partir do código-fonte)
pnpm (recomendado)

O pacote npm publicado inclui um binário bin/event pré-compilado, universal e assinado, portanto os usuários de npx não precisam de Xcode nem de toolchain Swift. Compilar a partir de um clone do git exige os itens acima.

Início Rápido

npx mcp-server-apple-events

Configuração

Adicione o servidor ao seu cliente MCP. A forma npx funciona para todos os clientes abaixo; para uma compilação local, substitua command/args por node apontando para dist/index.js.

Cursor

Configurações → MCP → Adicionar novo servidor MCP global:

{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["-y", "mcp-server-apple-events"]
    }
  }
}

ChatWise

Configurações → Ferramentas → "+", então:

Tipo: stdio
ID: apple-reminders
Comando: mcp-server-apple-events
Argumentos: (vazio)

Claude Desktop

Edite claude_desktop_config.json (abra via Configurações → Opção de Desenvolvedor → Editar Configuração, ou diretamente em ~/Library/Application Support/Claude/claude_desktop_config.json no macOS / %APPDATA%\Claude\claude_desktop_config.json no Windows):

{
  "mcpServers": {
    "apple-reminders": {
      "command": "npx",
      "args": ["-y", "mcp-server-apple-events"]
    }
  }
}

Para uma compilação local:

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

Consulte a documentação oficial do MCP para conectar servidores locais. Reinicie completamente o Claude Desktop (saia, não apenas feche) para que as alterações tenham efeito.

Permissões do macOS

O CLI event incluído incorpora seu próprio Info.plist (bundle id me.frad.event) declarando todas as strings de privacidade de Reminders e Calendar, e é iniciado por meio do shim bin/event-disclaim bundado, que declara não ter responsabilidade TCC no momento da inicialização. Portanto, o macOS atribui a solicitação de permissão a event em si, não ao aplicativo que iniciou o servidor MCP — assim, a primeira chamada EventKit solicita "event", a concessão aparece em System Settings > Privacy & Security > Reminders / Calendars como event, e uma única concessão cobre todos os clientes MCP na máquina (Claude Desktop, Codex Desktop, Cursor, clientes de terminal, …). Veja issue #93 para contexto.

Quando event detecta um status notDetermined, ele chama requestFullAccessToReminders / requestFullAccessToEvents, que exibe o prompt do sistema. Se o sistema operacional perder o controle das permissões, execute novamente ./check-permissions.sh para reabrir os diálogos.

Erros de leitura do Calendar

Se você vir Failed to read calendar events, defina Calendar para Full Calendar Access em System Settings > Privacy & Security > Calendars, ou execute novamente ./check-permissions.sh (ele verifica tanto Reminders quanto Calendars).

Recuperando um estado TCC travado (nenhum prompt aparece)

Se o diálogo de permissão nunca aparecer e event estiver ausente de System Settings → Privacy & Security → Reminders / Calendars, sua máquina está em um estado TCC desatualizado/mal atribuído. A correção de isenção no lado do servidor evita isso em uma máquina limpa, mas não pode limpar entradas já corrompidas. Recuperação:

Redefina as entradas TCC de Calendar e Reminders globalmente (a redefinição por aplicativo frequentemente não funciona — a forma simples limpa todas as entradas, que é o que limpa o estado ruim):
```
tccutil reset Calendar
tccutil reset Reminders
```
Isso limpa o acesso a Calendar/Reminders de todos os aplicativos; outros aplicativos solicitarão novamente na próxima vez.
Re-dispare a permissão de dentro de uma conversa no Claude (Claude Desktop ou Claude Code) pedindo, por exemplo, "Use AppleScript para verificar meu Calendar e Reminders." Conceda o acesso e o servidor deverá funcionar normalmente. Veja issue #83.

Execuções headless / launchd travam em vez de falhar

Quando o servidor roda em um contexto sem sessão GUI (SSH, agente/daemon launchd), a primeira chamada EventKit pode bloquear para sempre esperando um prompt de permissão que nunca pode ser renderizado — a solicitação MCP nunca se resolve e um processo filho vaza a cada chamada. O servidor agora encerra qualquer chamada event que exceda 30 s (SIGKILL) e retorna um erro legível. Ajuste com a variável de ambiente EVENTKIT_CLI_TIMEOUT_MS (milissegundos; valores inválidos/zero voltam ao padrão — o timeout não pode ser desabilitado, embora valores grandes até 2^31-1 ms sejam aceitos). O CLI event incluído (fixado via FradSer/event#15) adicionalmente falha rapidamente quando não há sessão GUI e desiste de um prompt impossível de responder após 15 s (EVENT_PERMISSION_TIMEOUT_MS), reportando Permission denied: Timed out waiting for ... para que o host possa mostrar uma mensagem específica de permissão antes do kill do servidor disparar (15 s < 30 s). Veja issue #113.

macOS 26 (Tahoe) `could not build module 'Foundation'`

Se pnpm build falhar com could not build module 'Foundation' (ou SDK is not supported by the compiler), sua toolchain Swift é mais antiga do que o SDK do macOS 26 exige — precisa de Swift 6.3 ou mais novo, mas as Command Line Tools enviadas com as versões iniciais do macOS 26 incluem Swift 6.2.x. pnpm build:event detecta isso e imprime a mesma correção; veja issue #85. Corrija instalando Xcode 26.x da App Store, ou atualizando as Command Line Tools para uma versão Swift 6.3+:

softwareupdate --list
sudo softwareupdate -i "Command Line Tools for Xcode-<latest>"
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer   # if full Xcode is installed
xcrun swiftc --version    # should report Apple Swift version 6.3 or newer

Exemplos de Uso

Uma vez configurado, peça ao Claude para interagir com seus Apple Reminders e Calendar. Exemplos de prompts:

Create a reminder to "Buy groceries" for tomorrow at 5 PM with tags shopping and errands.
Add a high-priority reminder to "Finish quarterly report" due Friday in my "Work" list.
Create "Grocery shopping" with subtasks: milk, eggs, bread, butter.
Show me all high-priority reminders due today tagged "urgent".
Show subtasks for my "Grocery shopping" reminder and mark "milk" as complete.
Update "Buy groceries" — change the title to "Buy organic groceries" and set priority to high.
Show reminders from my "Work" list, and list all my reminder lists.
Create a calendar event "Team standup" tomorrow from 9:00 to 9:30 in "Work".
Show my calendar events for the next week.

O servidor processa solicitações em linguagem natural, interage com os aplicativos nativos Reminders e Calendar da Apple e retorna resultados formatados.

Alarmes, regras de recorrência e gatilhos de localização são somente leitura por meio deste servidor — configure-os em Reminders.app / Calendar.app. Eles ainda aparecem nos resultados de leitura com indicadores visuais.

Ferramentas MCP Disponíveis

Ferramentas com escopo de serviço espelham os domínios de Apple Reminders e Calendar. Todas recebem um campo action além de parâmetros específicos da ação (o cliente MCP inspeciona o esquema Zod completo; apenas as ações são listadas aqui). Campos de data aceitam YYYY-MM-DD, YYYY-MM-DD HH:mm:ss (horário local) ou ISO 8601 com fuso horário.

Ferramenta	Ações	Notas
`reminders_tasks`	`read`, `create`, `update`, `delete`	Prioridade, tags, subtarefas. `startDate` é definido via `update`, não via `create`; em `read` ele define a janela de datas de vencimento junto com `endDate`. Movimentação entre listas não suportada.
`reminders_subtasks`	`read`, `create`, `update`, `delete`, `toggle`, `reorder`	Armazenado no campo de notas (legível em Reminders.app).
`reminders_lists`	`read`, `create`, `update`, `delete`	Renomear via `name` → `newName`.
`calendar_events`	`read`, `create`, `update`, `delete`	Dia inteiro inferido a partir do formato da data. Movimentação entre calendários não suportada. `span` define exclusões recorrentes.
`calendar_calendars`	`read`	Calendários com ≥1 evento na janela (opcional) `startDate`/`endDate`.

Exemplos de chamadas:

{
  "action": "create",
  "title": "Buy groceries",
  "dueDate": "2024-03-25 18:00:00",
  "targetList": "Shopping",
  "note": "Don't forget milk and eggs",
  "priority": 1,
  "tags": ["shopping", "errands"],
  "subtasks": ["Milk", "Eggs", "Bread"]
}

{ "action": "read", "filterList": "Work", "dueWithin": "today", "filterPriority": "high", "filterTags": ["urgent"] }

{ "action": "read", "startDate": "2026-08-01", "endDate": "2026-08-31" }

{ "action": "update", "id": "reminder-123", "completed": false, "addTags": ["followup"] }

{ "action": "toggle", "reminderId": "reminder-123", "subtaskId": "a1b2c3d4" }

{ "action": "create", "name": "Project Alpha" }

{ "action": "create", "title": "Team standup", "startDate": "2026-05-04 09:00:00", "endDate": "2026-05-04 09:30:00", "targetCalendar": "Work" }

Formato das respostas de leitura

As respostas de leitura trazem indicadores visuais: 🔄 recorrente, 📍 baseado em localização, 🏷️ tem tags, 📋 tem subtarefas. Exemplo:

- [ ] Buy groceries 🏷️📋
  - List: Shopping
  - ID: reminder-123
  - Priority: high
  - Tags: #shopping #errands
  - Subtasks (1/3):
    - [x] Milk
    - [ ] Eggs
    - [ ] Bread
  - Due: 2024-03-25 18:00:00

O campo url é armazenado na propriedade nativa url (visível pelo ícone "i" em Reminders.app) e também anexado às notas em um bloco estruturado URLs: para análise e suporte a múltiplas URLs. URLs aceitam qualquer esquema de URI válido (http, https, mailto, tel, obsidian, shortcuts, …); file, javascript, data e esquemas perigosos similares são rejeitados, e nomes de host http(s) são verificados contra uma lista de bloqueio SSRF.

Campos somente leitura: alarmes, regras de recorrência, gatilhos de localização, localizações estruturadas, url/availability/isAllDay do calendário e movimentação entre calendários não são graváveis por meio deste servidor — eles refletem os valores configurados em Reminders.app / Calendar.app. Veja docs/migration-to-event-cli.md para a tabela completa de campos removidos e alternativas.

Biblioteca de Prompts Estruturados

O servidor inclui um registro de prompts exposto por meio dos endpoints MCP ListPrompts / GetPrompt. Cada modelo compartilha uma missão, contextos de entrada, processo numerado, restrições, formato de saída e padrão de qualidade para que assistentes downstream obtenham uma estrutura previsível.

daily-task-organizer — today_focus opcional; produz um plano de execução para o mesmo dia, equilibra trabalho prioritário com recuperação, cria blocos de tempo no calendário automaticamente para lembretes com vencimento hoje.
smart-reminder-creator — task_idea opcional; gera uma estrutura de lembrete com agendamento otimizado.
reminder-review-assistant — review_focus opcional (ex.: overdue ou um nome de lista); audita e otimiza lembretes existentes.
weekly-planning-workflow — user_ideas opcional; guia uma redefinição de segunda a domingo com blocos de tempo vinculados a listas existentes.

Os prompts são limitados aos recursos nativos de Apple Reminders e pedem contexto ausente antes de ações irreversíveis. Execute pnpm test -- src/server/prompts.test.ts após alterar o texto dos prompts.

Desenvolvimento

pnpm install        # postinstall builds bin/event from vendor/event on macOS
pnpm build          # TypeScript + vendored event CLI
pnpm test           # Jest suite: repositories, schemas, build script, prompt templates
pnpm exec biome check   # lint + format

O ponto de entrada da CLI procura até dez diretórios para encontrar package.json, para que o servidor possa iniciar de caminhos aninhados (ex.: dist/ ou runners de tarefas do editor) sem perder bin/event. Mantenha o manifesto acessível nessa profundidade se você personalizar a estrutura de pastas.

Scripts

pnpm build — TypeScript + CLI event incluído (necessário antes de executar a partir do código-fonte)
pnpm build:ts — somente TypeScript
pnpm build:event — somente CLI event incluído (swift build -c release → bin/event)
pnpm build:release — compilação mais notarização (empacotamento de release)
pnpm test / pnpm test:ci — suíte Jest / com cobertura
pnpm lint — formatação/correção Biome + verificação de tipos TypeScript
pnpm check — lint + testes com cobertura

Licença

MIT

Contribuição

Contribuições são bem-vindas! Por favor, leia primeiro as diretrizes de contribuição.