# 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

```bash
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:

```bash
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:

```bash
npm run inspect
```

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

```bash
npm start
```

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

## In Claude Code registrieren

```bash
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`:

```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