mcp-for-apple-mail

Ein kleiner MCP-Server (Model Context Protocol), der Apple Mail auf dem Mac per AppleScript kapselt. Er hilft, Rechnungs-PDFs aus dem Posteingang zu finden und gezielt abzulegen, ohne Zugangsdaten zu hinterlegen: Apple Mail hat eine vollständige AppleScript-Schnittstelle und die Konten sind bereits eingerichtet.

Was ist ein MCP-Server?

MCP (Model Context Protocol) ist ein offener Standard, über den KI-Anwendungen (der Host, etwa Claude Desktop oder Claude Code) mit externen Werkzeugen und Daten sprechen. Ein Server stellt Fähigkeiten bereit und weiß selbst nichts von KI. Drei Arten:

• Tools — Aktionen, die das Modell aufrufen kann (hier: suchen, speichern).
• Resources — Daten zum Lesen (hier nicht genutzt).
• Prompts — Vorlagen (hier nicht genutzt).

Kommunikation läuft über JSON-RPC 2.0, hier per stdio (lokaler Prozess).

Tools

Tool	Zweck
list_mailboxes	Alle Konten und Mailboxen als <Konto>:<Mailbox> auflisten
search_messages	Nach Absender-Stichworten und/oder nur geflaggten Nachrichten im Zeitfenster suchen, mit Anhangnamen und Flaggen-Markierung (⚑)
save_attachment	Ersten passenden PDF-Anhang (Name enthält Schlüssel, endet auf .pdf) speichern
get_message_body	Klartext-Inhalt der ersten passenden Nachricht lesen (für Belege ohne PDF)
flag_message	Fahne an genau einer Nachricht setzen/entfernen, optional mit Farbe; bei mehrdeutigem Schlüssel passiert nichts

Installation

npm install

Kein Build-Schritt: reines ESM-JavaScript, läuft direkt mit Node (>= 18).

Konfiguration

Die zu durchsuchenden Mailboxen stehen in einer lokalen config.json, die nicht eingecheckt wird (in .gitignore). Vorlage kopieren und die eigenen Konten eintragen:

cp config.example.json config.json

Format je Eintrag <Konto>:<Mailbox>. Die exakten Namen liefert das Tool list_mailboxes. Fehlt die config.json, greifen generische Platzhalter.

Alternativ übergibt der Aufrufer die Mailboxen je Tool direkt im mailboxes-Parameter.

Lokal testen

Mit dem MCP Inspector zum Durchklicken der Tools:

npm run inspect

Oder direkt starten (wartet dann auf JSON-RPC über stdin):

npm start

Beim ersten echten Lauf fragt macOS nach Automatisierungs-Zugriff auf Mail. Einmal erlauben.

In Claude Code registrieren

claude mcp add apple-mail -- node /absolute/path/to/mcp-for-apple-mail/src/index.js

In Claude Desktop registrieren

In ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apple-mail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-for-apple-mail/src/index.js"]
    }
  }
}

Beispielablauf

1. list_mailboxes, um die exakten Konto- und Mailboxnamen zu sehen.
2. search_messages mit vendors: ["hosting", "software-vendor"] und fromDate: "2026-04-01", um zu sehen, welche Rechnungen als PDF vorliegen (Treffer zeigen die Anhangnamen in ATT{...}).
3. Pro Treffer save_attachment mit subjKey, attKey und destPath, z. B. nach dem Schema YYYY-MM/YYYY-MM-DD <Anbieter> <Beleg>.pdf.

Grenzen

• Nur macOS mit Apple Mail.
• Anbieter mit reinem Portal liefern per Mail kein PDF und müssen weiter manuell geladen werden.
• Steht die Rechnungsnummer nur im Anhang, nicht im Betreff, erst mit search_messages prüfen, wo der Schlüssel steht.

Lizenz

MIT