Apple Productivity MCP

Servidor MCP local gratuito para Apple Mail, Calendário e Lembretes no macOS.

Documentação

Apple Productivity MCP

Um servidor local e sob demanda do Model Context Protocol (MCP) que dá a Claude Code e Codex acesso controlado a Apple Mail, Calendar e Reminders no macOS.

Ele usa a interface de automação integrada da Apple por meio de /usr/bin/osascript. O transporte MCP é stdio: seu cliente MCP inicia o processo quando se conecta e o encerra quando a sessão o libera. Não há porta de escuta, serviço em segundo plano nem servidor MCP hospedado na nuvem.

Recursos

App	Ler e descobrir	Ações
Mail	Listar contas e caixas de correio, listar metadados de mensagens, ler uma mensagem	Enviar, marcar como lida/não lida, sinalizar/remover sinalização, mover, excluir
Calendar	Listar calendários, listar eventos em um intervalo de tempo	Criar, atualizar, excluir
Reminders	Listar listas de lembretes, listar lembretes	Criar, atualizar, concluir, excluir

O servidor publica anotações de ferramentas MCP para comportamento somente leitura, idempotente, destrutivo e de mundo aberto. Essas anotações ajudam clientes compatíveis a aplicar políticas de aprovação adequadas; elas não substituem a revisão de uma ação de escrita antes de aprová-la.

Requisitos

macOS com Mail, Calendar e Reminders
Node.js 20 ou mais recente
Claude Code, Codex CLI/aplicativo/extensão de IDE ou outro cliente MCP compatível com stdio
Permissão para o cliente que inicia o servidor automatizar os aplicativos Apple relevantes

Instalar a partir do npm

Este é o método de instalação recomendado. Não é necessário clonar o repositório nem instalar o pacote globalmente. npx baixa e armazena em cache o pacote publicado, e o cliente MCP o inicia como um processo filho stdio local quando uma sessão se conecta.

Confirme que Node.js e npx estão disponíveis:

node --version
npx --version

Os exemplos usam @latest para que novas sessões resolvam a versão publicada mais recente. Substitua por uma versão explícita, como @2.1.1, quando quiser uma instalação reproduzível e fixada.

Claude Code

Adicione o servidor à sua configuração de usuário para que ele fique disponível em todos os projetos:

claude mcp add --transport stdio --scope user apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest

Verifique o registro:

claude mcp get apple-productivity-local
claude mcp list

Inicie uma nova sessão do Claude Code após adicionar o servidor. Se o nome já estiver registrado, remova-o com claude mcp remove apple-productivity-local --scope user e execute o comando de adição novamente.

Aplicativo Codex, CLI e extensão de IDE

Adicione o servidor à configuração de usuário do Codex:

codex mcp add apple-productivity-local -- \
  npx -y @gambadio/apple-productivity-mcp@latest

Verifique o registro:

codex mcp get apple-productivity-local
codex mcp list

O aplicativo Codex, a CLI e a extensão de IDE compartilham esta configuração MCP no mesmo Mac. Inicie uma nova sessão após a instalação; reinicie um aplicativo ou extensão de IDE já aberto para que ele recarregue a configuração. Na CLI do Codex, /mcp mostra os servidores ativos.

Se o nome já estiver registrado, execute codex mcp remove apple-productivity-local e adicione novamente.

Outros clientes MCP locais

Use estes valores em qualquer cliente que possa iniciar um servidor MCP stdio local:

Configuração	Valor
Nome	`apple-productivity-local`
Transporte	`stdio`
Comando	`npx`
Argumentos	`-y`, `@gambadio/apple-productivity-mcp@latest`
Variáveis de ambiente	Nenhuma
Diretório de trabalho	Nenhum necessário

Clientes que aceitam o formato comum de configuração JSON podem usar:

{
  "mcpServers": {
    "apple-productivity-local": {
      "command": "npx",
      "args": [
        "-y",
        "@gambadio/apple-productivity-mcp@latest"
      ]
    }
  }
}

A chave de configuração externa e o local do arquivo variam conforme o cliente. Em uma tela de configuração gráfica, selecione STDIO e insira o comando e os argumentos da tabela. Esse padrão se aplica a clientes MCP locais, como Claude Desktop, Cursor, Windsurf, Cline e editores compatíveis; consulte a documentação do cliente para saber onde ele armazena a configuração MCP.

Se um cliente de desktop não conseguir encontrar npx, execute isto no Terminal:

command -v npx

Em seguida, substitua "command": "npx" pelo caminho absoluto retornado, por exemplo "command": "/usr/local/bin/npx".

Reinicie o cliente ou abra uma nova sessão após alterar a configuração MCP. Clientes que suportam apenas servidores HTTP remotos não podem executar este MCP diretamente porque o Apple Productivity MCP usa intencionalmente stdio local e automação do macOS.

Você não precisa executar npm start, instalar o pacote globalmente, manter um terminal aberto, configurar uma chave de API ou expor uma porta de rede.

Instalar a partir do código-fonte

Use um checkout do código-fonte ao desenvolver o servidor ou quando quiser executar um commit Git específico.

Clone o repositório e instale suas dependências fixadas:

git clone https://github.com/gambadio/apple-productivity-mcp.git
cd apple-productivity-mcp
npm ci

Capture os caminhos absolutos que os clientes MCP devem armazenar:

APPLE_MCP_NODE="$(command -v node)"
APPLE_MCP_SERVER="$(pwd)/src/index.js"

Caminhos com espaços são suportados. Mantenha as aspas nos comandos abaixo.

Claude Code com checkout do código-fonte

Instale o servidor para sua conta de usuário:

claude mcp add --transport stdio --scope user apple-productivity-local -- \
  "$APPLE_MCP_NODE" "$APPLE_MCP_SERVER"

Verifique o registro:

claude mcp get apple-productivity-local
claude mcp list

Codex com checkout do código-fonte

Instale o mesmo servidor stdio local no Codex:

codex mcp add apple-productivity-local -- \
  "$APPLE_MCP_NODE" "$APPLE_MCP_SERVER"

Verifique o registro:

codex mcp get apple-productivity-local
codex mcp list

O Codex armazena isso em sua configuração de usuário, compartilhada pelo aplicativo Codex, CLI e extensão de IDE no mesmo host. Inicie uma nova sessão após a instalação. Se um aplicativo de desktop ou extensão de IDE já estava aberto, reinicie-o para que ele recarregue a configuração MCP.

Você não precisa executar npm start nem manter um terminal aberto. O cliente MCP inicia o checkout do código-fonte como um processo filho quando estabelece a conexão MCP.

Conceder permissão do macOS

A primeira chamada real de ferramenta para cada aplicativo Apple pode acionar um prompt de Automação do macOS. Aprove o acesso para o aplicativo que iniciou o servidor MCP, como Terminal, iTerm, Claude Code, Codex ou sua IDE.

Se você negou um prompt ou nenhum prompt apareceu:

Abra System Settings → Privacy & Security → Automation.
Encontre o aplicativo que inicia seu cliente MCP.
Ative Mail, Calendar e Reminders conforme necessário.
Reinicie o cliente MCP e tente novamente.

Experimente

Comece com as ferramentas de descoberta para que o cliente aprenda os nomes locais exatos configurados no seu Mac:

"Liste minhas contas e caixas de correio do Apple Mail."
"Liste meus calendários Apple graváveis."
"Liste minhas listas do Apple Reminders."
"Mostre os eventos de todos os calendários de amanhã."
"Mostre meus lembretes incompletos."

O Mail usa por padrão o nome de conta iCloud e a caixa de correio INBOX quando um chamador não fornece nomes. Use apple_mail_list_accounts primeiro se sua configuração usar nomes diferentes.

Referência de ferramentas

Mail

apple_mail_list_accounts — listar nomes de contas, endereços de remetentes e caixas de correio
apple_mail_list — listar metadados de mensagens sem ler os corpos
apple_mail_get — ler uma mensagem, incluindo seu corpo
apple_mail_send — enviar uma mensagem imediatamente
apple_mail_update_status — marcar como lida/não lida ou sinalizar/remover sinalização
apple_mail_move — mover uma mensagem para outra caixa de correio na mesma conta
apple_mail_delete — excluir uma mensagem usando o comportamento do Mail.app

Calendar

apple_calendar_list_calendars — listar nomes de calendários e status de gravação
apple_calendar_list_events — listar eventos sobrepostos em um intervalo de tempo ISO 8601
apple_calendar_create_event — criar um evento
apple_calendar_update_event — atualizar um evento por UID
apple_calendar_delete_event — excluir um evento por UID

Reminders

apple_reminders_list_lists — listar nomes e IDs de listas de lembretes
apple_reminders_list — listar lembretes, opcionalmente incluindo itens concluídos
apple_reminders_create — criar um lembrete
apple_reminders_update — atualizar um lembrete por ID
apple_reminders_complete — marcar um lembrete como concluído
apple_reminders_delete — excluir um lembrete por ID

Privacidade e segurança

O próprio servidor MCP não tem listener de rede e não armazena credenciais nem dados da Apple.
As entradas são passadas para osascript como argumentos JSON, em vez de serem interpoladas em código-fonte JXA executável.
Alterações em Mail, Calendar e Reminders podem ser sincronizadas via iCloud, CalDAV, Exchange ou outro provedor configurado.
"MCP local" descreve onde o servidor é executado. O conteúdo retornado a Claude Code ou Codex passa a fazer parte da sessão ativa do modelo e pode ser processado de acordo com os controles de dados desse produto.
Enviar, mover, atualizar, concluir e excluir são ações reais. Revise as solicitações de ferramentas de escrita antes de aprová-las.

Atualizar

Registros que usam o comando npm com @latest resolvem a versão publicada mais recente quando um novo processo MCP é iniciado. Inicie uma nova sessão do Claude Code ou Codex após um lançamento. Fixe uma versão explícita se atualizações automáticas não forem desejáveis.

Para um checkout do código-fonte, atualize no local para que o caminho absoluto armazenado permaneça válido:

cd /absolute/path/to/apple-productivity-mcp
git pull --ff-only
npm ci
npm test

Remover

claude mcp remove apple-productivity-local --scope user
codex mcp remove apple-productivity-local

Remover o registro não limpa o cache do npm, não exclui um repositório clonado nem altera dados da Apple.

Desenvolvimento e verificação

Instale as dependências e execute a suíte de testes isolada:

npm ci
npm test
npm audit --omit=dev

Execute os testes de integração ao vivo somente leitura após conceder a permissão de Automação:

npm run test:integration

A execução padrão de testes ignora os testes de integração ao vivo porque eles acessam os aplicativos Apple instalados do usuário.

Solução de problemas

`Apple automation unavailable` ou um erro de autorização

Revise System Settings → Privacy & Security → Automation, ative o aplicativo Apple afetado para o processo que inicia seu cliente MCP e reinicie o cliente.

`Mail account not found`, `Calendar not found` ou `Reminder list not found`

Execute a ferramenta de descoberta correspondente e use o nome exato retornado. Os nomes são locais à sua configuração do macOS e podem diferir por idioma ou provedor.

`spawn ... ENOENT`

Para uma instalação via npm, execute command -v npx e use o caminho absoluto retornado como o comando configurado. Para um checkout do código-fonte, remova e adicione novamente o registro MCP usando valores novos de command -v node e pwd.

O pacote npm não pode ser baixado

Confirme que o pacote público está acessível e que o cliente tem acesso à internet para a primeira instalação:

npm view @gambadio/apple-productivity-mcp version

Depois que o pacote for baixado, o npm pode reutilizar seu cache local para essa versão.

O servidor está registrado, mas as ferramentas não aparecem

Execute os comandos mcp get/mcp list do cliente e inicie uma nova sessão. Reinicie um aplicativo de desktop ou extensão de IDE já aberto após alterar a configuração MCP.

Licença

MIT

Apple Productivity MCP

Documentação