Apple-MCPs

Servidores MCP locais para macOS para Mail, Calendário, Lembretes, Notas, Contatos, Mensagens, Atalhos, Arquivos, Mapas e ferramentas do sistema.

GitHub

Experimente este MCPPatrocinado

Documentação

Apple-MCPs

Servidores MCP para usar aplicativos Apple e ferramentas macOS a partir de um cliente de IA.

Os servidores podem criar lembretes, enviar mensagens, verificar calendários, pesquisar e-mails, gerenciar arquivos e obter rotas através do Model Context Protocol (MCP). As integrações rodam no seu Mac e funcionam com os aplicativos Apple que você já usa. Os dados retornados a um cliente MCP podem ser enviados ao provedor de modelo desse cliente, e os aplicativos Apple podem sincronizar seus dados através do iCloud ou de outra conta configurada.

Apple-MCPs é gratuito e de código aberto sob a Licença MIT.

Construído sobre a especificação MCP 2026-07-28 (Python SDK 2.x) com compatibilidade retroativa para clientes que falam revisões de protocolo mais antigas.

Instalação

Executar a partir do PyPI (uvx)

Instale o uv e depois execute o servidor unificado:

uvx apple-tools-mcp

Servidores independentes funcionam da mesma forma. Por exemplo, use uvx apple-mcp-mail ou uvx apple-calendar-mcp.

Claude Code

claude mcp add --transport stdio --scope project apple-tools -- uvx apple-tools-mcp

Codex

Registre o servidor unificado com o Codex CLI:

codex mcp add apple-tools -- uvx apple-tools-mcp

Reinicie o cliente após a instalação ou atualizações e depois chame search_tools com uma consulta como calendar health para verificar a descoberta sem ler dados de aplicativos.

Cliente MCP genérico (config JSON stdio)

{
  "mcpServers": {
    "apple-tools": {
      "command": "uvx",
      "args": ["apple-tools-mcp"]
    }
  }
}

Configure modos de segurança e diretórios específicos do aplicativo nas configurações de env do seu cliente. Consulte o guia de configuração do Apple Tools para ver as configurações disponíveis e os padrões.

Anexos de e-mail são desativados, a menos que APPLE_MAIL_MCP_ALLOWED_ATTACHMENT_ROOT aponte para um diretório dedicado. As ferramentas de arquivos permanecem limitadas a APPLE_FILES_MCP_ALLOWED_ROOTS, e os controles de privacidade do macOS podem limitar ainda mais o acesso a pastas como Área de Trabalho, Documentos, Downloads ou iCloud Drive.

Claude Desktop

Baixe o pacote .mcpb para um servidor em Releases e clique duas vezes nele. O Claude Desktop instala o pacote e gerencia sua configuração.

A partir de um clone

git clone https://github.com/JonathanRReed/Apple-MCPs.git
cd Apple-MCPs
uv sync --all-packages

Isso cria um ambiente de workspace com todos os pontos de entrada do servidor em .venv/bin, incluindo .venv/bin/apple-tools-mcp. Cada pasta de servidor também tem um start.sh que os clientes MCP podem chamar diretamente. O script usa uv quando disponível e, caso contrário, cria um ambiente virtual simples.

Servidores

Apple-Tools-MCP é o ponto de partida recomendado. Ele combina Mail, Calendar, Reminders, Messages, Contacts, Notes, Shortcuts, Files, System e Maps em um único servidor. Também possui padrões salvos, preferências de roteamento por contato, auxiliares de thread de e-mail, suporte a desfazer, ferramentas de briefing e fluxos de trabalho entre aplicativos.

Use um servidor independente quando quiser expor menos aplicativos Apple ao cliente:

Permissões do macOS

O macOS controla o acesso aos aplicativos Apple e aos dados protegidos. Cada servidor tem ferramentas para relatar seu acesso atual, explicar a permissão necessária e verificar novamente após uma mudança. Você deve aprovar ou alterar as permissões do macOS por conta própria no prompt do sistema ou nas Ajustes do Sistema.

Servidor	O que o macOS pode solicitar	Ferramenta de saúde	Ferramentas de recuperação
Apple-Tools-MCP	Tudo abaixo, conforme usado	`apple_health`	`apple_permission_guide`, `apple_recheck_permissions`
Mail	Acesso de automação ao Mail	`mail_health`	`mail_permission_guide`, `mail_recheck_permissions`
Calendar	Acesso ao Calendar	`calendar_health`	`calendar_permission_guide`, `calendar_recheck_permissions`
Reminders	Acesso ao Reminders	`reminders_health`	`reminders_permission_guide`, `reminders_recheck_permissions`
Messages	Acesso de automação ao Messages, além de Acesso Total ao Disco para histórico	`messages_health`	`messages_permission_guide`, `messages_recheck_permissions`
Contacts	Acesso ao Contacts	`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 nenhum prompt de privacidade separado	`shortcuts_health`	`shortcuts_permission_guide`, `shortcuts_refresh_state`
Files	O acesso é limitado às raízes permitidas configuradas; o macOS também pode exigir acesso a pastas protegidas	`files_health`	`files_permission_guide`
System	System Events, Accessibility ou prompts de automação para algumas ações	`system_health`	`system_permission_guide`
Maps	Nenhum prompt de privacidade; o auxiliar Swift local precisa das ferramentas de linha de comando do Xcode	`maps_health`	`maps_permission_guide`

Encontrar e usar ferramentas

Cada servidor lista suas ferramentas disponíveis através do MCP tools/list, incluindo esquemas de entrada e saída e anotações de leitura ou escrita. Duas ferramentas auxiliares facilitam a busca em um catálogo grande:

search_tools: pesquisar nomes de ferramentas, descrições e aliases
get_tool_info: ler o esquema, os metadados e os exemplos de uma ferramenta

Notas de uso

Resolva uma pessoa através do Contacts antes de enviar uma mensagem, a menos que você já tenha o endereço exato do destinatário.
Use os auxiliares de thread de e-mail (mail_get_thread, mail_reply_latest_in_thread, mail_archive_thread) quando o usuário mencionar uma conversa.
Reminders é para itens com prazo, Notes para material de referência, Calendar para horários agendados.
Quando o Mail precisar enviar de uma identidade específica, passe o e-mail exato do remetente em from_account.
A pesquisa do Mail exige uma string de consulta: um remetente, um fragmento de assunto ou * como curinga.
Reminders due_date exige um deslocamento de fuso horário como yyyy-MM-ddTHH:mm:ss-08:00.
Omita service_name em envios pelo iMessage.
Apple-Tools-MCP inclui ferramentas de briefing: apple_generate_daily_briefing, apple_generate_weekly_briefing e apple_triage_communications_task.
Ferramentas de fallback por prompt (apple_list_prompts, apple_get_prompt e equivalentes por servidor) cobrem clientes que só suportam ferramentas.

Wrappers Python

O repositório inclui wrappers Python gerados para clientes que chamam ferramentas MCP a partir de código:

generated/tool_catalogs/: metadados de ferramentas pesquisáveis para cada servidor
generated/tool_wrappers/python/: wrappers Python para cada ferramenta

Consulte docs/code-mode.md para a estrutura dos wrappers, a interface do cliente e o fluxo de trabalho recomendado.

Transportes e verificações de protocolo

stdio é o transporte padrão para uso local. Cada servidor também suporta streamable-http através de variáveis de ambiente. Defina APPLE_<DOMAIN>_MCP_TRANSPORT=streamable-http e as variáveis correspondentes _HOST e _PORT. As ligações HTTP devem usar um endereço de loopback como 127.0.0.1, ::1 ou localhost. Os servidores não têm autenticação remota. Eles rejeitam ligações de rede e curinga e não devem ser expostos através de túnel ou proxy público.

Execute a suíte oficial de conformidade MCP contra o Apple-Tools-MCP:

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

Verificações rápidas de fumaça do Inspector em todos os servidores:

bash scripts/inspector_smoke.sh
uv run python scripts/protocol_smoke.py

O CI executa lint, a suíte de testes completa no macOS e Linux, verificações de desvio de artefatos gerados, verificações de fumaça do Inspector e a suíte de conformidade. Consulte .github/workflows.

Estrutura do repositório

Apple-Tools-MCP/: servidor unificado, módulo apple_agent_mcp, prefixo de ambiente APPLE_AGENT_MCP_*
Apple<Domain>-MCP/: servidores independentes. A pasta do calendário é Apple-Calendar-MCP.
AppleMCPCommon/: auxiliares compartilhados de descoberta e pesquisa, publicados como apple-mcp-common
generated/: catálogos de ferramentas gerados e wrappers Python
scripts/: scripts de instalação, verificação de protocolo, geração de artefatos e build de pacotes
docs/: documentação do projeto e de lançamento

O repositório é um workspace uv: pyproject.toml na raiz define os membros, e uv.lock fixa todo o grafo de dependências.

Documentação do projeto

CHANGELOG.md
CONTRIBUTING.md
SECURITY.md
Code Mode
Compatibilidade MCP
Solução de problemas: permissões do macOS, tempos limite e códigos de erro comuns
Publicação
NOTICE.md: aviso de marca registrada
Documentação de lançamento: fluxos de trabalho, modos de falha, compatibilidade e script de demonstração

Notas

Apple-Tools-MCP persiste padrões de assistente em ~/.apple-tools-mcp/preferences.json (ou APPLE_AGENT_MCP_STATE_FILE) e ações recentes do assistente em ~/.apple-tools-mcp/actions.json para fluxos de auditoria e desfazer.
APPLE_AGENT_MCP_CONFORMANCE_MODE=1 é apenas para validação de protocolo; ele registra os fixtures oficiais de conformidade.