# IMAP MCP

Lokaler MCP-Server, der Claude Zugriff auf beliebige IMAP-Postfächer gibt und E-Mails über SMTP versendet.
Läuft komplett auf deinem Rechner — Zugangsdaten und Mails verlassen die Maschine nur Richtung deines Mailservers.

Es gibt zwei Wege:

| | [Weg A: Fertiges Bundle](#weg-a-fertiges-bundle) | [Weg B: Aus dem Quellcode](#weg-b-aus-dem-quellcode) |
| --- | --- | --- |
| Für wen | alle, die einfach ihr Postfach anbinden wollen | Entwicklung, mehr als zwei Postfächer, Linux, Claude Code |
| Postfächer | bis zu zwei | beliebig viele |
| Voraussetzungen | nur Claude Desktop (macOS oder Windows) | Node ≥ 18.17, Terminal |
| Installation | Datei doppelklicken, Adresse + Passwort eintippen | klonen, bauen, JSON konfigurieren |
| Server-Einstellungen | automatisch erkannt | automatisch oder von Hand |
| Passwort liegt | im Schlüsselbund des Systems | im Klartext in `config.json` |

---

# Weg A: Fertiges Bundle

Claude Desktop bringt auf macOS und Windows eine eigene Node-Laufzeit mit. Als `.mcpb`-Bundle verpackt
braucht der Server weder Node noch Terminal noch Git.

## Installieren

1. **[`imap-mail.mcpb` herunterladen](https://github.com/abconsultdev/imap-mcp/releases/latest/download/imap-mail.mcpb)**
   (rund 1 MB, dieselbe Datei für macOS und Windows).
2. Die Datei doppelklicken — alternativ ins Claude-Desktop-Fenster ziehen oder unter
   Einstellungen → Erweiterungen → Erweiterte Einstellungen → Erweiterung installieren auswählen.
3. Im Installationsdialog **E-Mail-Adresse** und **Passwort** eintragen. Alle anderen Felder sind optional.
4. Installieren, fertig. Kein Neustart nötig.

Erster Test im Chat: *„Teste die Mail-Verbindung"*.

Das Bundle ist nicht signiert. Claude Desktop kann deshalb beim Installieren auf einen unbekannten
Herausgeber hinweisen.

**Was im Dialog abgefragt wird**

| Feld | |
| --- | --- |
| E-Mail-Adresse | Pflichtfeld |
| Passwort | Pflichtfeld. Landet im **Schlüsselbund** (macOS) bzw. der **Anmeldeinformationsverwaltung** (Windows), nicht in einer Datei |
| Senden erlauben | Standardmäßig **aus** — Claude kann dann lesen und Entwürfe anlegen, aber nichts verschicken |
| Absendername | optional |
| Zweites Postfach: Adresse, Passwort, Senden, Absendername | optional — leer lassen, wenn nur ein Postfach gebraucht wird |
| Server online nachschlagen | siehe [Server-Erkennung](#wie-die-server-erkennung-funktioniert) |
| IMAP-/SMTP-Server (je Postfach) | leer lassen, nur nötig, wenn die Erkennung scheitert |

Anhänge landen im Downloads-Ordner.

## Vor der Einrichtung

Die meisten Probleme entstehen nicht im Connector, sondern beim Mail-Anbieter:

- **Gmail, iCloud, Yahoo:** Das normale Passwort wird abgelehnt. Nötig ist ein App-Passwort aus den
  Kontoeinstellungen, bei Gmail zusätzlich aktivierte Zwei-Faktor-Anmeldung.
- **GMX, Web.de:** IMAP ist standardmäßig aus und muss im Webmail unter Einstellungen freigeschaltet werden.
- **Microsoft 365 / Outlook:** Viele Organisationen haben die Anmeldung per Passwort abgeschaltet. Dann
  lässt sich das Postfach mit diesem Connector nicht anbinden (siehe [Einschränkungen](#einschränkungen)).
- **Eigene Domain:** Funktioniert in der Regel ohne weitere Angaben, weil der Anbieter über den
  MX-Eintrag der Domain erkannt wird.

Wer vorab wissen will, ob eine Adresse erkannt wird, kann Claude mit `mail_detect_provider` fragen —
das braucht weder Passwort noch Anmeldung.

Wo der Anbieter App-Passwörter anbietet, lohnen sie sich auch ohne Pflicht: Sie lassen sich einzeln
widerrufen, ohne das Postfach-Passwort zu ändern.

## Erste Schritte

Gute erste Fragen, die nur lesen und nichts verändern:

- *„Was ist heute ungelesen reingekommen?"*
- *„Fass mir den längsten Mailverlauf dieser Woche zusammen."*
- *„Von welchen Newslettern bekomme ich am meisten Mails?"*

Senden bleibt so lange aus, bis es im Dialog freigegeben wird. Wer den Versand ausprobieren will,
schickt die erste Testmail am besten an die eigene Adresse.

## Zwei Postfächer

Im Dialog lassen sich bis zu zwei Postfächer einrichten, auch bei verschiedenen Anbietern. Jedes wird
getrennt erkannt, und **Senden wird je Postfach einzeln freigegeben**: Man kann etwa das private
Postfach nur lesbar lassen und nur im geschäftlichen den Versand erlauben.

Sobald zwei eingerichtet sind, nennt Claude das Postfach bei jedem Zugriff über seine Adresse. Fehlt
diese Angabe, kommt eine Rückfrage statt einer stillen Annahme — das zählt vor allem beim Senden, damit
keine Mail vom falschen Absender rausgeht. Im Chat reicht es, das Postfach beim Namen zu nennen:
*„Was ist heute im Geschäftspostfach reingekommen?"*

Mehr als zwei gehen über das Bundle nicht, weil das Manifest-Format keine beliebig langen Feldlisten
kennt. Über `config.json` (Weg B) ist die Zahl unbegrenzt.

## Wie die Server-Erkennung funktioniert

Niemand muss seinen IMAP-Server kennen. Der Connector probiert der Reihe nach:

1. **Eingebaute Anbieterliste** — Gmail, GMX, Web.de, T-Online, Posteo, mailbox.org, iCloud, Yahoo,
   Outlook und weitere, erkannt an der Domain der Adresse.
2. **MX-Eintrag der Domain** — der wichtigste Fall bei eigenen Domains. `info@meinefirma.de` mit einem
   MX-Eintrag auf `smtpin.rzone.de` wird als Strato-Postfach erkannt. Deckt Strato, IONOS, All-Inkl,
   Hetzner, netcup, domainFACTORY, united-domains, Google Workspace und Microsoft 365 ab.
3. **Mozillas Autoconfig-Datenbank** — dieselbe Quelle, aus der Thunderbird seine Einstellungen zieht.
4. **Raten** aus der Domain (`imap.<domain>`), klar als unbestätigt gekennzeichnet.

Schritte 2 und 3 brauchen Netzwerk und fragen dabei **nur die Domain** ab, nie die Adresse oder das
Passwort. Wer das nicht möchte, schaltet „Server online nachschlagen" aus; dann greift nur die
eingebaute Liste, und seltenere Anbieter müssen von Hand eingetragen werden.

## Aktualisieren und entfernen

**Update:** Unter Einstellungen → Erweiterungen die alte Version deinstallieren, dann die neue Datei
installieren. Die Zugangsdaten werden dabei neu abgefragt.

**Entfernen:** Ebenfalls über Einstellungen → Erweiterungen. Die Passwörter werden dabei aus dem
Schlüsselbund gelöscht, es bleiben keine Zugangsdaten auf dem Rechner zurück.

---

# Weg B: Aus dem Quellcode

## 1. Installieren

```bash
git clone https://github.com/abconsultdev/imap-mcp.git
cd imap-mcp && npm install && npm run build
```

## 2. Konfigurieren

`config.example.json` nach `config.json` kopieren und ausfüllen. Die Datei enthält Passwörter im
Klartext und steht deshalb in `.gitignore`.

```json
{
  "accounts": [
    {
      "name": "hauptpostfach",
      "email": "info@example.com",
      "displayName": "Dein Name",
      "allowSend": true,
      "imap": { "host": "imap.example.com", "port": 993, "secure": true, "user": "info@example.com", "pass": "..." },
      "smtp": { "host": "smtp.example.com", "port": 465, "secure": true, "user": "info@example.com", "pass": "..." }
    }
  ]
}
```

| Feld | Bedeutung |
| --- | --- |
| `name` | Kurzname, den du im Chat benutzt (*„lies die Mails im hauptpostfach"*) |
| `displayName` | Absendername im From-Header |
| `allowSend` | `false` = reiner Lesezugriff, `mail_send` verweigert dann den Dienst |
| `secure` | `true` bei Port 993/465 (direktes TLS), `false` bei 143/587 (STARTTLS) |
| `allowInvalidCert` | nur für interne Server mit selbstsigniertem Zertifikat |
| `enableIMAP4rev2` | IMAP4rev2 nutzen, falls der Server es anbietet. Standard aus, siehe [Fehlersuche](#fehlersuche) |
| `mailboxes` | optional, überschreibt die Auto-Erkennung von Gesendet/Entwürfe/Papierkorb |
| `downloadDir` | (oberste Ebene) Ordner für Anhänge, Standard `<projekt>/downloads` |

Mehrere Postfächer: einfach weitere Objekte in `accounts` eintragen. Bei mehr als einem Account
verlangt jedes Tool den Parameter `account`.

### Gängige Server

| Anbieter | IMAP | SMTP | Hinweis |
| --- | --- | --- | --- |
| Gmail / Workspace | `imap.gmail.com:993` | `smtp.gmail.com:465` | App-Passwort nötig (2FA erforderlich) |
| Microsoft 365 / Outlook | `outlook.office365.com:993` | `smtp.office365.com:587` (`secure: false`) | Passwort-Anmeldung oft gesperrt, siehe Einschränkungen |
| IONOS | `imap.ionos.de:993` | `smtp.ionos.de:465` | |
| Strato | `imap.strato.de:993` | `smtp.strato.de:465` | |
| All-Inkl | `<server>.kasserver.com:993` | `<server>.kasserver.com:465` | |
| mailbox.org | `imap.mailbox.org:993` | `smtp.mailbox.org:465` | eigenes App-Passwort empfohlen |
| GMX / Web.de | `imap.gmx.net:993` / `imap.web.de:993` | `mail.gmx.net:465` / `smtp.web.de:465` | IMAP muss in den Einstellungen freigeschaltet sein |

### Alternative: Umgebungsvariablen

Ohne `config.json` genügen `MAIL_EMAIL` und `MAIL_PASSWORD` für einen Account — die Server werden dann
automatisch erkannt. Das ist auch der Weg, den das `.mcpb`-Bundle nutzt. **Umgebungsvariablen haben
Vorrang vor `config.json`.**

| Variable | |
| --- | --- |
| `MAIL_EMAIL`, `MAIL_PASSWORD` | Pflicht |
| `MAIL_ALLOW_SEND` | `true` schaltet den Versand frei. **Standard ist aus** |
| `MAIL_DISPLAY_NAME` | Absendername |
| `MAIL_IMAP_HOST`, `MAIL_SMTP_HOST` | überschreiben die Erkennung |
| `MAIL_IMAP_PORT`, `MAIL_SMTP_PORT` | Ports, Standard 993 / 465 |
| `MAIL2_EMAIL`, `MAIL2_PASSWORD`, `MAIL2_ALLOW_SEND`, `MAIL2_DISPLAY_NAME`, `MAIL2_IMAP_HOST`, `MAIL2_SMTP_HOST`, … | dasselbe für ein zweites Postfach |
| `MAIL_AUTODETECT_ONLINE` | `false` schaltet MX- und Online-Abfrage ab (gilt für beide) |
| `MAIL_DOWNLOAD_DIR` | Ordner für Anhänge, Standard `~/Downloads` |
| `IMAP_MCP_CONFIG` | abweichender Pfad zur `config.json` |

Werte, die noch einen unersetzten Platzhalter der Form `${...}` enthalten, werden als *nicht gesetzt*
behandelt. Die älteren Namen `IMAP_HOST`, `IMAP_USER`, `IMAP_PASS`, `IMAP_PORT`, `SMTP_HOST`,
`SMTP_PORT`, `SMTP_USER`, `SMTP_PASS` funktionieren weiterhin.

## 3. In Claude eintragen

Der Server spricht MCP über stdio. In Claude Desktop unter Einstellungen → Entwickler → Konfiguration
bearbeiten eintragen — der Pfad muss absolut sein:

```json
{
  "mcpServers": {
    "imap": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/imap-mcp/dist/index.js"]
    }
  }
}
```

Die Datei liegt unter `%APPDATA%\Claude\claude_desktop_config.json` (Windows) bzw.
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). Unter Windows werden
Backslashes im Pfad verdoppelt (`"C:\\Users\\...\\dist\\index.js"`) oder durch `/` ersetzt; unter
macOS wird `~` nicht aufgelöst. Startet der Server nicht, weil Claude Desktop Node nicht findet
(typisch bei nvm oder Homebrew), statt `"node"` den vollen Pfad aus `which node` eintragen.

Danach Claude Desktop **komplett beenden und neu starten** — MCP-Server werden nur beim Start geladen.

In Claude Code:

```bash
claude mcp add imap --scope user -- node /absoluter/pfad/zu/imap-mcp/dist/index.js
```

Erster Test im Chat: *„Teste die Mail-Verbindung"* → ruft `mail_test_connection` auf und meldet IMAP und
SMTP getrennt.

Mehrere Rechner können parallel auf dasselbe Postfach zugreifen — IMAP ist dafür gebaut. Die
`config.json` dabei auf jedem Rechner neu anlegen, statt sie zu kopieren.

---

# Referenz

## Tools

**Lesen**

| Tool | Zweck |
| --- | --- |
| `mail_list_accounts` | Eingerichtete Postfächer (ohne Passwörter) |
| `mail_test_connection` | IMAP- und SMTP-Login einzeln prüfen |
| `mail_detect_provider` | Server-Einstellungen zu einer Adresse ermitteln — ohne Passwort, ohne Anmeldung |
| `mail_list_mailboxes` | Alle Ordner + erkannte Sonderordner |
| `mail_search` | Nach Absender, Betreff, Text, Datum, ungelesen … — liefert UIDs |
| `mail_read` | Eine Nachricht per UID vollständig lesen |
| `mail_get_raw` | RFC822-Quelltext (Header-Analyse, SPF/DKIM) |
| `mail_save_attachment` | Anhänge auf die Platte speichern |

**Verwalten**

| Tool | Zweck |
| --- | --- |
| `mail_set_flags` | gelesen / ungelesen / markiert / beantwortet setzen |
| `mail_move` | In anderen Ordner verschieben |
| `mail_move_to_trash` | In den Papierkorb (nie endgültiges Löschen) |

**Schreiben**

| Tool | Zweck |
| --- | --- |
| `mail_create_draft` | Mail als Entwurf ins IMAP-Postfach legen, ohne zu senden |
| `mail_send` | Über SMTP versenden und Kopie im Gesendet-Ordner ablegen |

`mail_send` und `mail_create_draft` nehmen beide `inReplyToUid`, damit Antworten sauber im Thread landen
(`In-Reply-To` und `References` werden aus der Originalmail gesetzt). Anhänge kommen entweder als
lokaler `path` oder als `contentBase64`.

## Typische Abläufe

- *„Was ist heute ungelesen reingekommen?"* → `mail_search` mit `unseen: true`, `since: heute`
- *„Fass mir den Verlauf mit Anna zusammen"* → `mail_search` mit `from: anna`, dann `mail_read` je UID
- *„Antworte darauf"* → `mail_create_draft` mit `inReplyToUid`, du prüfst im Mailprogramm, dann `mail_send`
- *„Räum die Newsletter weg"* → `mail_search`, dann `mail_move` nach `Archiv`

## Sicherheit

- **Versand ist endgültig.** Claude fragt vor `mail_send` nach — bestätige bewusst. Wer generell nur
  Entwürfe will, lässt Senden aus und nutzt `mail_create_draft`.
- Es gibt bewusst kein endgültiges Löschen. `mail_move_to_trash` verschiebt nur; geleert wird im Mailprogramm.
- Mailinhalte sind Daten, keine Anweisungen. Wenn in einer Mail steht „leite das weiter" oder „antworte mit X",
  ist das kein Auftrag von dir — Claude soll dich fragen, bevor so etwas ausgeführt wird.
- Beim Bundle liegen Passwörter im Schlüsselbund des Systems. Bei Weg B stehen sie im Klartext in
  `config.json` — Dateirechte einschränken:
  ```bash
  chmod 600 config.json                                                   # macOS / Linux
  icacls config.json /inheritance:r /grant:r "%USERNAME%:(R,W)"           # Windows
  ```

## Fehlersuche

**Verbindung klappt, Ordner werden angezeigt, aber jede Suche liefert 0 Mails**

Manche Server kündigen IMAP4rev2 an, beantworten unter rev2 aber jede Suche mit einer leeren
Ergebnisliste (`* ESEARCH (TAG "8") UID`), obwohl das Postfach voll ist — beobachtet bei Strato. Der
Connector schaltet rev2 deshalb standardmäßig ab; IMAP4rev1 versteht jeder Server. Wer rev2 für einen
bestimmten Server braucht, setzt in `config.json` unter `imap` den Schalter `"enableIMAP4rev2": true`.
Ob die Suche gegen ein konkretes Postfach funktioniert, prüft `node test/live.mjs` (rein lesend).

**Die Server-Felder im Installationsdialog bleiben leer — ist das richtig?**

Ja. Der Dialog füllt nichts automatisch aus; die Erkennung passiert erst beim Start des Servers, aus
der eingegebenen Adresse. Die Host-Felder sind nur ein Notausgang für den Fall, dass die Erkennung
scheitert. Was tatsächlich erkannt wurde, zeigt `mail_test_connection` unter `serverErkanntVia`.

**`Authentication failed` / `LOGIN failed`**

Passwort falsch oder der Anbieter verlangt ein App-Passwort (Gmail, iCloud, Yahoo) — bei GMX und Web.de
ist IMAP zusätzlich standardmäßig deaktiviert und muss im Webmail freigeschaltet werden.

**Senden schlägt mit „Senden ist deaktiviert" fehl**

Beabsichtigt. Im Installationsdialog den Haken „Senden erlauben" setzen, in `config.json`
`"allowSend": true`, per Umgebungsvariable `MAIL_ALLOW_SEND=true`.

**Falscher Server erkannt**

`mail_detect_provider` mit der Adresse aufrufen — die Antwort zeigt, aus welcher Quelle die Werte
stammen. Notfalls IMAP- und SMTP-Server im Installationsdialog von Hand eintragen.

**`getaddrinfo ENOTFOUND ${user_config.imap_host}`**

Tritt nur mit Versionen vor 1.0.1 auf. Alte Erweiterung deinstallieren, aktuelle installieren.

## Einschränkungen

- **Nur Passwort-Authentifizierung.** Kein OAuth2/XOAUTH2. Postfächer, bei denen der Anbieter die
  Passwort-Anmeldung abgeschaltet hat (viele Microsoft-365-Organisationen), lassen sich damit nicht anbinden.
- Die Volltextsuche macht der IMAP-Server, nicht dieser Connector — wie gut `body`/`text` funktioniert,
  hängt vom Anbieter ab.
- `mail_search` holt Kopfdaten für bis zu 200 Treffer pro Aufruf.
- Kein Push/IDLE — Claude sieht neue Mails, wenn es aktiv nachschaut.

## Entwicklung

```bash
npm run build              # nach dist/ kompilieren (Weg B)
npm run watch              # während der Entwicklung
npm run bundle             # build/imap-mail.mcpb bauen, inkl. aller Prüfungen (Weg A)
node test/unit.mjs         # Helfer + MailComposer (ohne Netzwerk)
node test/detect.mjs       # Anbieter-Erkennung: Liste, MX-Muster, Autoconfig
node test/env-matrix.mjs   # Konfiguration über Umgebungsvariablen, 15 Fälle
node test/live.mjs         # gegen das echte Postfach aus config.json, rein lesend
```

**Das Bundle** wird mit esbuild zu einer einzigen JavaScript-Datei gebündelt: vier Dateien statt rund
5000, knapp 1 MB statt 6 MB. Ohne Bündelung lägen Typdeklarationen, Sourcemaps und die HTTP-Transporte
des MCP-SDK im Bundle, die ein stdio-Server nie lädt.

Bündeln kann dynamisch nachgeladene Module zerreißen — `iconv-lite` lädt Zeichensatz-Tabellen zur
Laufzeit, `mailparser` und `MailComposer` ziehen Module über `require()` herein. Ein solcher Bruch fiele
sonst erst beim ersten Umlaut in einer echten Mail auf. Deshalb prüft `npm run bundle` sein eigenes
Ergebnis, bevor gepackt wird: Zeichensatz-Umwandlung, Anhänge, Mail-Aufbau und die komplette
Konfigurationsmatrix laufen gegen die gebündelte Datei (`test/bundle-libs.ts` wird dafür eigens
mitgebündelt). Schlägt eine Prüfung fehl, entsteht kein `.mcpb`. Mit `npm run bundle -- --skip-checks`
lässt sich das überspringen.

**Der Live-Test** ist der einzige, der einen echten Mailserver fragt. Er vergleicht, was der Server laut
`STATUS` enthält, mit dem, was die Suche findet — eine erfolgreiche Verbindung und eine vollständige
Ordnerliste allein beweisen nicht, dass die Suche funktioniert. Vor einer neuen Version lohnt es sich,
ihn mit Postfächern der wichtigsten Anbieter laufen zu lassen. Die MX-Erkennung einer eigenen Domain
lässt sich live mit `TEST_MX_EMAIL=name@domain.de node test/detect.mjs` prüfen.

IMAP-Verbindungen werden pro Account wiederverwendet und nach 5 Minuten Leerlauf geschlossen.

## Versionen

| Version | |
| --- | --- |
| 1.1.0 | Zweites Postfach im Installationsdialog, Senden je Postfach getrennt |
| 1.0.2 | IMAP4rev2 standardmäßig aus (leere Suchergebnisse bei Strato); neueste Mails ohne Suche |
| 1.0.1 | Leer gelassene Dialogfelder kamen als Platzhalter an und verhinderten die Server-Erkennung |
| 1.0.0 | Erste Version |

## Lizenz

MIT — siehe [LICENSE](LICENSE).