Apple-MCPs
Servidores MCP locais para macOS para Mail, Calendário, Lembretes, Notas, Contatos, Mensagens, Atalhos, Arquivos, Mapas e ferramentas do sistema.
Documentação
Apple-MCPs
Servidores MCP que permitem que um cliente de IA use aplicativos Apple e ferramentas do macOS. Crie lembretes, envie mensagens, verifique calendários, pesquise e-mails, gerencie arquivos e obtenha rotas.
Os servidores são executados no seu Mac. Seu cliente MCP pode enviar os dados retornados ao provedor de modelo, e os aplicativos Apple podem sincronizar via iCloud ou outra conta. A execução local não significa que os dados permanecem locais.
Requer Python 3.11+ e macOS. Usa a especificação MCP 2026-07-28 e o SDK Python 2.x, com suporte para revisões de protocolo de clientes mais antigas. Licença MIT.
Instalação
Instale o uv e registre o servidor unificado com seu cliente.
Claude Code:
claude mcp add --transport stdio --scope project apple-tools -- uvx apple-tools-mcp
Codex:
codex mcp add apple-tools -- uvx apple-tools-mcp
Outros clientes stdio:
{
"mcpServers": {
"apple-tools": {
"command": "uvx",
"args": ["apple-tools-mcp"]
}
}
}
Execute uvx apple-tools-mcp para iniciar o servidor diretamente. Servidores independentes usam a mesma abordagem, como uvx apple-mcp-mail ou uvx apple-calendar-mcp.
Reinicie seu cliente após instalar ou atualizar. Chame search_tools com calendar health para verificar a descoberta sem ler dados de aplicativos.
Para Claude Desktop, baixe o pacote .mcpb de um servidor em Releases e clique duas vezes nele.
Defina modos de segurança e diretórios específicos de aplicativos nas configurações de env do seu cliente. Uma configuração de segurança explicitamente inválida ou em branco seleciona safe_readonly; configurações não definidas mantêm o padrão documentado de cada domínio. O guia de configuração lista padrões e opções. Anexos de e-mail são desativados até que você defina APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT para um diretório dedicado. As ferramentas de arquivos acessam apenas APPLE_FILES_MCP_ALLOWED_ROOTS; o macOS pode impor restrições adicionais.
Escolha um servidor
Comece com Apple-Tools-MCP. Ele combina todos os dez aplicativos e ferramentas abaixo, além de padrões salvos, roteamento de contatos, auxiliares de conversas de e-mail, desfazer, resumos e fluxos de trabalho entre aplicativos.
Escolha um servidor independente para expor menos aplicativos ao seu cliente:
| Servidor | Acesso ao macOS | Ferramenta de saúde | Ajuda de permissão |
|---|---|---|---|
| Acesso de automação ao Mail | mail_health | mail_permission_guide, mail_recheck_permissions | |
| Calendar | Acesso ao Calendário | calendar_health | calendar_permission_guide, calendar_recheck_permissions |
| Reminders | Acesso a Lembretes | reminders_health | reminders_permission_guide, reminders_recheck_permissions |
| Messages | Automação; Acesso Total ao Disco para histórico | messages_health | messages_permission_guide, messages_recheck_permissions |
| Contacts | Acesso a Contatos | contacts_health | contacts_permission_guide, contacts_recheck_permissions |
| Notes | Acesso de automação ao Notes | notes_health | notes_permission_guide, notes_recheck_permissions |
| Shortcuts | Geralmente sem prompt separado | shortcuts_health | shortcuts_permission_guide, shortcuts_refresh_state |
| Files | Raízes permitidas e acesso a pastas protegidas | files_health | files_permission_guide |
| System | Algumas ações precisam de Eventos do Sistema, Acessibilidade ou Automação | system_health | system_permission_guide |
| Maps | Sem prompt de privacidade; o auxiliar Swift precisa das ferramentas de linha de comando do Xcode | maps_health | maps_permission_guide |
O servidor unificado usa apple_health, apple_permission_guide e apple_recheck_permissions. Você deve aprovar as permissões pessoalmente no prompt do macOS ou nas Configurações do Sistema.
Encontre e use ferramentas
O MCP tools/list retorna os esquemas de cada ferramenta e anotações de leitura ou escrita. Use search_tools para pesquisar nomes, descrições e aliases; use get_tool_info para o esquema e exemplos de uma ferramenta.
Resolva destinatários por meio de Contatos antes de enviar, a menos que você tenha o endereço exato. Para conversas de e-mail, use mail_get_thread, mail_reply_latest_in_thread ou mail_archive_thread. Passe um e-mail exato do remetente em from_account quando a identidade de envio for importante.
A pesquisa de e-mail requer uma consulta: um remetente, fragmento de assunto ou *. Lembretes due_date requer um deslocamento de fuso horário, como yyyy-MM-ddTHH:mm:ss-08:00. Omita service_name ao enviar iMessages.
O servidor unificado também fornece apple_generate_daily_briefing, apple_generate_weekly_briefing e apple_triage_communications_task. Clientes sem suporte a prompts podem usar apple_list_prompts, apple_get_prompt e seus equivalentes por servidor.
Para chamadas em Python, use os metadados em generated/tool_catalogs/ e os wrappers em generated/tool_wrappers/python/. Veja code-mode.md.
Transporte e estado armazenado
stdio é o padrão. Para usar Streamable HTTP, defina APPLE_<DOMAIN>_MCP_TRANSPORT=streamable-http e as variáveis correspondentes _HOST e _PORT.
O HTTP deve vincular a 127.0.0.1, ::1 ou localhost. Os servidores não têm autenticação remota e rejeitam vínculos de rede e curinga. Não os exponha por meio de túnel ou proxy público.
O Apple-Tools-MCP armazena padrões em ~/.apple-tools-mcp/preferences.json, configurável por meio de APPLE_AGENT_MCP_STATE_FILE. Ele armazena ações recentes em ~/.apple-tools-mcp/actions.json para auditoria e desfazer.
Desenvolvimento
git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages
O workspace uv instala cada servidor em .venv/bin. Cada pasta de servidor também tem um start.sh para clientes; ele usa uv quando disponível e, caso contrário, cria um ambiente virtual. O pyproject.toml raiz define membros do workspace, e uv.lock fixa dependências.
| Caminho | Conteúdo |
|---|---|
Apple-Tools-MCP/ | Servidor unificado; módulo apple_agent_mcp, prefixo de ambiente APPLE_AGENT_MCP_* |
Apple<Domain>-MCP/ | Servidores independentes; Calendar usa Apple-Calendar-MCP |
AppleMCPCommon/ | Descoberta e pesquisa compartilhadas, publicado como apple-mcp-common |
generated/ | Catálogos de ferramentas e wrappers Python |
scripts/ | Instalação, verificações, geração e builds de pacotes |
docs/ | Documentação do projeto e de lançamento |
Execute verificações rápidas:
bash scripts/inspector_smoke.sh
uv run python scripts/protocol_smoke.py
Para a suíte oficial de conformidade, inicie o servidor em um terminal separado:
APPLE_AGENT_MCP_TRANSPORT=streamable-http \
APPLE_AGENT_MCP_PORT=8765 \
APPLE_AGENT_MCP_CONFORMANCE_MODE=1 \
./Apple-Tools-MCP/start.sh
npx -y @modelcontextprotocol/conformance@0.2.0-alpha.11 server --url http://127.0.0.1:8765/mcp --requirements 2026-07-28
O modo de conformidade registra fixtures de teste. Use-o apenas para validação de protocolo. CI executa lint, testes de macOS e Linux, verificações de arquivos gerados, verificações rápidas do Inspector e testes de conformidade.
Documentação
Contribuindo · Segurança · Solução de problemas · Compatibilidade MCP · Publicação · Changelog · Aviso de marca registrada · Documentos de lançamento