mcp-hey

Ein lokaler Model Context Protocol (MCP)-Server, der Claude Lese-/Schreibzugriff auf Ihren Hey.com-Posteingang über Reverse-Engineered-Web-APIs gewährt.

mcp-hey besteht aus zwei beweglichen Teilen: einem Bun/TypeScript-MCP-Server, der Hey-Tools über stdio bereitstellt, und einem kleinen Python-Helfer, der die System-Webview verwendet, um Sitzungs-Cookies bei der Anmeldung zu erfassen. Alles läuft lokal – kein Cloud-Relay, keine gespeicherten Anmeldedaten, nur Sitzungs-Cookies auf der Festplatte.

Hinweis – inoffizielle API. Hey.com veröffentlicht keine öffentliche API; mcp-hey führt Reverse-Engineering der Web-Endpunkte durch und kombiniert sie mit browseridentischen HTTP-Anfragen. Dinge können ohne Vorankündigung kaputtgehen. Die aktuell dokumentierte Oberfläche befindet sich in docs/API.md.

Funktionen

• E-Mails aus Imbox, Feed, Paper Trail, Set Aside und Reply Later lesen

• E-Mail-Threads senden und beantworten

• E-Mails über alle Postfächer hinweg durchsuchen

• E-Mails organisieren (zur Seite legen, später antworten, screenen, nach oben schieben)

• Lokaler SQLite-Cache für schnelleres wiederholtes Lesen und Volltextsuche

• Leichtgewichtig – ca. 30 MB Speicherverbrauch im Leerlauf

• Browseridentische Header und TLS-Konfiguration zur Vermeidung von Erkennung

• Läuft vollständig auf Ihrem Rechner; stdio-Transport ohne Netzwerkfreigabe

Einrichtung

Voraussetzungen

• Bun 1.1 oder neuer

• Python 3.10 oder neuer (plus UV, falls Sie den Python-Tools in CLAUDE.md folgen möchten)

• Ein Hey.com-Konto

• Plattform: entwickelt und getestet auf macOS und Linux. Windows-Benutzer benötigen wahrscheinlich WSL – das Windows-Backend von pywebview wird derzeit nicht genutzt.

Installation

1. Dieses Repository klonen

   git clone https://github.com/Sealjay/mcp-hey.git
   cd mcp-hey

2. Abhängigkeiten installieren

   bun install
   pip install -r auth/requirements.txt

3. Erster Lauf – Authentifizierung

   bun run dev

   Der Python-Authentifizierungshelfer öffnet eine System-Webview, die auf Hey.com zeigt. Melden Sie sich wie gewohnt an; der Helfer erfasst Sitzungs-Cookies in data/hey-cookies.json (Berechtigungen auf 600 gesetzt) und beendet sich. Nachfolgende Läufe verwenden die gespeicherte Sitzung wieder, bis sie abläuft.

MCP-Client-Konfiguration

Claude Desktop

Fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) hinzu:

{
  "mcpServers": {
    "hey": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-hey/src/index.ts"]
    }
  }
}

Starten Sie Claude Desktop neu. Sie sollten hey als verfügbare Integration sehen.

Cursor

Fügen Sie dies zu ~/.cursor/mcp.json hinzu:

{
  "mcpServers": {
    "hey": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/mcp-hey/src/index.ts"]
    }
  }
}

Starten Sie Cursor neu.

Architektur

Datenfluss

1. Der MCP-Client (Claude Desktop / Cursor) startet bun run src/index.ts über stdio.

2. Beim Start validiert der Server data/hey-cookies.json. Falls diese fehlt oder abgelaufen ist, startet er auth/hey-auth.py, das Hey in einer System-Webview öffnet und neue Cookies schreibt.

3. Tool-Aufrufe erreichen Hey.com direkt mit browserrealistischen Headern; Antworten werden geparst (HTML via node-html-parser) und in SQLite zwischengespeichert.

4. Schreibvorgänge rufen vor dem Absenden ein frisches CSRF-Token ab.

Projektstruktur

mcp-hey/
  src/
    index.ts           # MCP server entry point
    hey-client.ts      # HTTP client with cookie injection
    session.ts         # Session management and validation
    errors.ts          # Error classes and sanitisation
    cache/             # SQLite cache (db, schema, messages, search)
    tools/             # MCP tool implementations
      read.ts          # Reading and listing
      send.ts          # Send, reply, forward
      organise.ts      # Triage, labels, bubble up, etc.
      http-helpers.ts  # Shared CSRF retry and endpoint fallback
    __tests__/         # Test suites
  auth/
    hey-auth.py        # Python auth helper (pywebview)
    requirements.txt
  data/
    hey-cookies.json   # Session storage (gitignored, chmod 600)
  docs/
    API.md             # Hey.com API surface documentation
    TOOLS.md           # MCP tool reference (41 tools)

Verfügbare Tools

41 Tools, gruppiert nach Funktion. Siehe docs/TOOLS.md für Parameter, Rückgabeformate und Fehlerverhalten.

Datenschutz und Sicherheit

• Es werden niemals Anmeldedaten gespeichert – nur Sitzungs-Cookies, geschrieben mit 600-Berechtigungen.

• Die Authentifizierung erfolgt vollständig innerhalb der eigenen Anmeldeseite von Hey (System-Webview).

• Alle Daten verbleiben auf Ihrem Rechner. Von diesem Projekt wird keine Telemetrie gesendet.

• MCP verwendet stdio-Transport – der Server öffnet niemals einen Netzwerk-Listener.

• Die Gültigkeit der Sitzung wird beim Start und vor sensiblen Vorgängen überprüft.

Siehe SECURITY.md für Informationen zur Meldung von Sicherheitslücken.

Einschränkungen

• Prompt-Injection-Risiko: Wie bei vielen MCP-Servern unterliegt auch dieser dem tödlichen Dreigestirn. Eine bösartige E-Mail, die in Ihrem Posteingang landet, könnte versuchen, Claude anzuweisen, andere Nachrichten zu exfiltrieren. Behandeln Sie die Tool-Oberfläche entsprechend und überprüfen Sie riskante Aktionen, bevor Sie sie genehmigen.

• Inoffizielle API: Das Frontend von Hey.com kann sich ohne Vorankündigung ändern und Dinge beschädigen. Rechnen Sie mit gelegentlichen Ausfällen und prüfen Sie docs/API.md auf bekannte Änderungen.

• Keine Echtzeit-Benachrichtigungen: nur Polling.

• Anhang-Uploads werden noch nicht unterstützt.

• Ein Konto pro MCP-Server-Instanz.

• Kontorisiko: Aggressive oder anormale Zugriffsmuster könnten theoretisch die Anti-Missbrauchs-Systeme von Hey auslösen. Der Server respektiert x-ratelimit-Header und wartet exponentiell ab, aber es gibt keine Garantien.

Fehlerbehebung

• Auth-Webview öffnet sich nicht – bestätigen Sie, dass Python 3.10+ im PATH ist und pip install -r auth/requirements.txt erfolgreich war. Stellen Sie unter Linux sicher, dass ein Webview-Backend verfügbar ist (python -c "import webview" sollte keinen Fehler ausgeben).

• 401/403-Antworten nach wochenlanger Nutzung – Ihre Hey-Sitzung ist abgelaufen. Löschen Sie data/hey-cookies.json und führen Sie bun run dev erneut aus, um sich neu zu authentifizieren.

• Ratenbegrenzungen (429) – der Client respektiert x-ratelimit-Header und wartet ab. Wenn Sie anhaltende 429er sehen, reduzieren Sie die gleichzeitige Tool-Nutzung oder warten Sie einige Minuten.

• Bun kann das Skript in Claude Desktop/Cursor nicht finden – der args-Pfad muss absolut sein, nicht relativ, und bun muss aus der Startumgebung des Clients heraus auffindbar sein (unter macOS kann dies bedeuten, einen vollständigen Pfad wie /opt/homebrew/bin/bun zu verwenden).

• Cookie-Name geändert – Hey hat Sitzungs-Cookies schon früher umbenannt (z. B. _hey_session → session_token, siehe CLAUDE.md für das Protokoll). Wenn die Authentifizierung nach einem Hey-Update stillschweigend fehlschlägt, erfassen Sie neue Cookies und vergleichen Sie diese.

Mitwirken

Beiträge sind über Pull Requests willkommen. Bitte:

• Verwenden Sie konventionelle Commits (feat, fix, docs, refactor, test, perf, cicd, revert, WIP).

• Führen Sie bun run format und bun run lint vor dem Pushen aus.

• Stellen Sie sicher, dass bun test besteht.

• Aktualisieren Sie docs/API.md, falls Sie ein Verhalten der Hey.com-API entdecken oder ändern.

Siehe CLAUDE.md für den vollständigen Entwicklungs-Workflow.

Lizenz

MIT-Lizenz – siehe LICENCE.