icloud-mcp

MCP-server voor iCloud, bedoeld om 24/7 op de Synology (Docker) te draaien. Mail en Agenda.

Wat er bewust niet in zit: Herinneringen (Structured doet dat), Foto's (Synology Photos) en iCloud Drive (geen officiële API en geen app-specifiek wachtwoord; de pc kopieert de map met robocopy naar een NAS-share).

Tools

mail_list_folders, mail_search, mail_read, mail_attachment, mail_send, mail_mark, mail_trash.

mail_read toont per bijlage een index; mail_attachment haalt daarmee de tekst uit PDF, Word, Excel, PowerPoint en tekstbestanden (alleen lezen, in het geheugen, niets op schijf). Scans en afbeeldingen geven een uitleg in note; OCR volgt later. Grenzen via MCP_MAX_ATTACHMENT_MB (standaard 15) en MCP_MAX_ATTACHMENT_CHARS (standaard 50000).

Gmail

Alle mailtools hebben een argument account (icloud, standaard, of gmail). Gmail werkt via IMAP/SMTP met een app-wachtwoord: zet GMAIL_ADDRESS en GMAIL_APP_PASSWORD in .env en herstart met --force-recreate. Zonder die variabelen geeft account=gmail een duidelijke foutmelding. Alle mail staat in één map waarvan de naam van de taal afhangt ([Gmail]/All Mail, [Gmail]/Alle e-mail); mail_list_folders toont hem. De prullenbak wordt automatisch gevonden. Zoeken kan met Gmail-syntax door de zoekopdracht met gmail: te laten beginnen, bv. gmail:has:attachment filename:pdf newer_than:30d. Versturen en verwijderen vragen ook voor Gmail confirm=true. Het app-wachtwoord geeft toegang tot de hele mailbox: bewaar .env zoals het iCloud-wachtwoord en trek het in bij twijfel.

Agenda: agenda_list_calendars, agenda_list_events, agenda_create_event, agenda_delete_event (CalDAV met je Apple-ID en app-specifiek wachtwoord). mail_send, mail_trash, agenda_create_event en agenda_delete_event doen niets zonder confirm=true; zonder krijg je een voorbeeld terug.

Related MCP server: iCloud MCP

Snel starten

Je hebt nodig: een machine die 24/7 aanstaat met Docker (NAS, Raspberry Pi, kleine server), een eigen domeinnaam, en een iCloud-account met een app-specifiek wachtwoord.

git clone https://github.com/dlife/mcp-icloud && cd mcp-icloud
./setup.sh          # Engels: ./setup.sh --lang en
docker compose up -d --build

setup.sh heeft alleen Docker nodig. De wizard vraagt je Apple-ID, het iCloud-mailadres, het app-specifieke wachtwoord (met uitleg waar je dat maakt), optioneel Gmail en het publieke adres. Hij test de logins (Mail, Agenda, Gmail), maakt een sterk aanmeldwachtwoord voor Claude aan en schrijft .env (alleen leesbaar voor jou). Daarna volg je de volgende stappen die hij toont: reverse proxy en connector in Claude.

Liever met de hand? cp .env.example .env, vul in en start met docker compose up -d --build. Test op de machine zelf: curl http://127.0.0.1:8765/healthz geeft ok; /mcp zonder aanmelding geeft 401. Op een Synology kan het ook via Container Manager, Project, Aanmaken.

English: see README.en.md.

Publiek bereikbaar maken

Zet een reverse proxy met HTTPS voor 127.0.0.1:8765 (of poort 8000 van de container).

Synology DSM (aanbevolen): Configuratiescherm, Aanmeldingsportaal, Geavanceerd, Reverse Proxy, Aanmaken. Bron: HTTPS, hostnaam icloud.example.com, poort 443. Bestemming: HTTP, localhost, poort 8765. Koppel daarna in Beveiliging, Certificaat, Instellingen een certificaat aan die regel (dat moet icloud.example.com bevatten). De aanmelding gebeurt in de server zelf, een extra token-laag in de proxy is niet nodig (en zou de OAuth-stroom van Claude blokkeren).

Caddy:

icloud.example.com {
    reverse_proxy icloud-mcp:8000
}

Draait Caddy in een eigen Docker-netwerk, zet de container dan in dat netwerk (zie commentaar in docker-compose.yml). Vergeet het DNS-record en de port-forward naar 443 niet.

Koppelen met Claude

In Claude: Instellingen, Connectors, Aangepaste connector toevoegen, URL https://icloud.example.com/mcp. Claude registreert zichzelf, je krijgt een inlogpagina van je eigen server en geeft met MCP_OWNER_PASSWORD toegang. Tokens staan (als hash) in het volume icloud-mcp-data; toegang intrekken doe je door dat volume te verwijderen.

Bijwerken

In de projectmap: git pull, dan sudo docker compose up -d --build --force-recreate. Na een wijziging in .env is sudo docker compose up -d --force-recreate genoeg (een gewone herstart leest .env niet opnieuw). Nieuwe tools verschijnen in Claude pas na een nieuw gesprek, of na de connector uit en aan te zetten.

Instellingen in .env

Zie .env.example (met uitleg per variabele); ./setup.sh maakt het bestand voor je. Het Apple-ID (voor de Agenda) en het mailadres van iCloud Mail kunnen verschillen: zet dan het iCloud-adres in ICLOUD_MAIL_ADDRESS. LOG_LEVEL (standaard INFO) stelt het logboek in.

Logboek

sudo docker compose logs --tail 50. Het logboek bevat per aanroep alleen toolnaam, duur en uitkomst, nooit onderwerpen, adressen of inhoud.

Back-up

sh scripts/backup.sh /pad/naar/doelmap bewaart .env en het OAuth-volume (de laatste 14 keer). Plan dat in DSM, Taakplanner, als gebruikersscript als root. Het bestand bevat je app-wachtwoord en tokens: bewaar het in een map die alleen jij kunt lezen. Terugzetten: pak het archief uit, zet env terug als .env en pak oauth-data.tgz uit in een nieuw volume icloud-mcp-data.

Problemen oplossen

• AUTHENTICATIONFAILED bij Mail: gebruik een app-specifiek wachtwoord en het volledige iCloud-mailadres in ICLOUD_MAIL_ADDRESS (iCloud Mail bestaat alleen met een @icloud.com-adres of eigen domein bij iCloud).

• Invalid Host header: MCP_ALLOWED_HOSTS moet de hostnaam bevatten waarop de server bereikbaar is.

• Nieuwe tool niet zichtbaar in Claude: nieuw gesprek starten of de connector opnieuw aanzetten.

• Opnieuw koppelen met Claude: verwijder de connector en voeg hem opnieuw toe; je logt dan weer in met MCP_OWNER_PASSWORD.

Ontwikkelen

pip install -e '.[dev]' && pytest