convez.ai
MCP ServerAutomaçãoIntermediário
gheydon

Apple MCP Server

gheydon/apple-mcp

Integre Calendar, Reminders, Contacts, Photos e Messages do macOS com Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP nativo em Swift que expõe Calendar, Reminders, Contacts, Photos e Messages do macOS para agentes de IA como Claude. Oferece acesso integrado às principais aplicações Apple sem dependências externas, apenas um binário Swift compilado estaticamente.

Instalação

$npx convez-ai gheydon/apple-mcp

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
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.3.0
Issues abertas
1
Contribuidores
1

Casos de uso

  • Automação de agendamentos e lembretes via agentes IA
  • Busca e organização de contatos e fotos programaticamente
  • Envio de mensagens e consulta de iMessage/SMS com Claude
  • Sincronização de tarefas entre Claude e sistema operacional

Veredito

Solução robusta para usuários macOS que querem integrar deeply seus dados nativos com Claude. Implementação limpa em Swift sem dependências externas; excelente para fluxos de produtividade pessoal e automação de desktop.

README

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

apple-mcp

A native-Swift Model Context Protocol server that exposes macOS Calendar, Reminders, Contacts, Photos, and Messages to AI agents (Claude Code, Claude Desktop, etc.). No Node, no Python, no shell glue — one statically-linked Swift binary.

Install

Homebrew (recommended)

brew install gheydon/apple-mcp/apple-mcp

Installs a notarized universal (arm64 + x86_64) binary at $(brew --prefix)/bin/apple-mcp.

Download a pre-built binary

Grab the latest tarball from the Releases page — it contains a notarized universal binary that runs on Intel and Apple Silicon Macs.

tar -xzf apple-mcp-*-macos.tar.gz
mv apple-mcp /usr/local/bin/   # or wherever

Build from source

Requires Swift 6.0+ (Xcode 16+) on macOS 14+.

git clone https://github.com/gheydon/apple-mcp.git
cd apple-mcp
swift build -c release

The binary lands at .build/release/apple-mcp.

Tools

ToolDescription
calendar_list_calendarsList all calendars on the system
calendar_list_eventsList events in a date range
calendar_create_eventCreate a new event
reminders_list_listsList reminder lists
reminders_listList reminders, filter by list/status/due date
reminders_createCreate a reminder
reminders_completeMark a reminder complete
contacts_searchSearch contacts by name, phone or email; returns phones, emails, addresses, URLs, birthday
contacts_createCreate a new contact
photos_list_albumsList user-created and non-empty smart albums
photos_searchFilter photos by date range, favorites, media type, and/or album
photos_exportSave a full-resolution photo or video to disk
photos_viewReturn a downsized JPEG of an image asset as inline image content
messages_list_chatsList recent iMessage/SMS chats
messages_recentRecent messages, optionally per chat
messages_searchSubstring search over the text column
messages_sendSend a message via Messages.app

Wire into Claude Code / Claude Desktop

Automatic (recommended)

After installing, run:

apple-mcp register

It detects which MCP hosts you have installed (Claude Desktop, Claude Code), prints what it would change, asks for confirmation per host, and adds an apple entry to each mcpServers block pointing at the running binary. Existing entries for other MCP servers are preserved; the prior config is backed up to <config>.bak.

Flags:

  • --host claude-desktop|claude-code — target only one host
  • --yes / -y — non-interactive; assume yes
  • --path <path> — register a specific binary location instead of the running executable

To remove the entry later, run apple-mcp unregister (same flags apply).

Manual

If you'd rather edit the config yourself, add to your MCP host config (claude_desktop_config.json or ~/.claude.json):

{
  "mcpServers": {
    "apple": {
      "command": "/opt/homebrew/bin/apple-mcp"
    }
  }
}

On Intel Macs the Homebrew path is /usr/local/bin/apple-mcp. If you built from source, point at /absolute/path/to/apple-mcp/.build/release/apple-mcp.

Permissions

macOS will prompt for these the first time each tool group is used:

  1. Calendar — System Settings → Privacy & Security → Calendar
  2. Reminders — System Settings → Privacy & Security → Reminders
  3. Contacts — System Settings → Privacy & Security → Contacts
  4. Photos — System Settings → Privacy & Security → Photos
  5. Automation → Messages — granted on first messages_send
  6. Full Disk Access — must be granted manually to the parent process (Terminal, iTerm, Claude Desktop) to read ~/Library/Messages/chat.db

How it works

ConcernImplementation
Calendar / RemindersEventKit (EKEventStore, requestFullAccessToEvents / requestFullAccessToReminders)
ContactsContacts framework (CNContactStore)
PhotosPhotoKit (PHPhotoLibrary, PHAsset, PHImageManager); thumbnails JPEG-encoded via NSBitmapImageRep
Messages readingDirect SQLite3 access to ~/Library/Messages/chat.db
attributedBody decodingHand-written typedstream scanner — modern Messages stores body text in an NSArchiver-format BLOB, not in the text column
Messages sendingNSAppleScript driving Messages.app (Apple provides no public Swift API for sending iMessages)
MCP protocolOfficial modelcontextprotocol/swift-sdk

Known limitations

  • messages_search only matches the text column. Messages whose body lives solely in attributedBody are not matched. Decoding every blob on search would be costly.
  • AppleScript message sending works best for recipients you've already exchanged messages with. Apple has progressively restricted Messages scripting on newer macOS versions.

Releasing

NOTARY_PROFILE=apple-mcp-notary scripts/release.sh 0.2.0

Builds a universal binary, signs it with a Developer ID Application identity, notarizes via the named keychain profile, and writes dist/apple-mcp-0.2.0-macos.tar.gz ready to upload to a GitHub release.

License

GPL-2.0 — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados