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 Teilen: einem Bun/TypeScript-MCP-Server, der Hey-Tools über stdio bereitstellt, und einem kleinen Python-Helfer, der das System-Webview nutzt, um Sitzungs-Cookies bei der Anmeldung zu erfassen. Alles läuft lokal – kein Cloud-Relay, keine gespeicherten Anmeldedaten, nur Sitzungs-Cookies auf der Festplatte.

Warnung – inoffizielle API. Hey.com veröffentlicht keine öffentliche API; mcp-hey nutzt Reverse-Engineering für die Web-Endpunkte und kombiniert diese mit browseridentischen HTTP-Anfragen. Dinge können ohne Vorwarnung kaputtgehen. Die aktuell dokumentierte Oberfläche befindet sich in docs/API.md.

Funktionen

• E-Mails aus Imbox, Feed, Paper Trail, Set Aside, Reply Later, Entwürfen, Papierkorb und Spam lesen

• Anhänge herunterladen und Kalendereinladungen aus E-Mails parsen

• E-Mail-Threads senden und beantworten

• E-Mails über alle Ordner hinweg durchsuchen

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

• Lokaler SQLite-Cache für schnellere wiederholte Lesezugriffe und Volltextsuche

• Leichtgewichtig – ca. 30 MB Arbeitsspeicher im Leerlauf

• Browseridentische Header und TLS-Konfiguration zur Vermeidung von Erkennung

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

Related MCP server: email-mcp

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
   uv pip install -r auth/requirements.txt

3. Erster Start – Authentifizierung

   bun run dev

   1. Ein System-Webview öffnet sich mit der Anmeldeseite von Hey.com. Melden Sie sich normal an.

   2. Der Helfer erfasst die Sitzungs-Cookies in data/hey-cookies.json (Berechtigungen 600) und beendet sich.

   3. Drücken Sie Strg+C – Ihr MCP-Client startet ab jetzt seine eigene Serverinstanz.

   4. Nachfolgende Ausführungen verwenden die gespeicherte Sitzung wieder, bis sie abläuft.

MCP-Client-Konfiguration

Alle unten aufgeführten Clients verwenden dieselbe command/args-Struktur. Unter macOS benötigen Sie fast sicher den absoluten Pfad zu bun – siehe macOS: bun PATH unten.

Claude Code

Der schnellste Weg ist die CLI:

claude mcp add --transport stdio hey --scope user -- bun run /absolute/path/to/mcp-hey/src/index.ts

Der Server ist sofort in der aktuellen Sitzung verfügbar.

Alternativ fügen Sie dies zu .mcp.json in Ihrem Projektstammverzeichnis hinzu (oder ~/.claude.json für einen benutzerspezifischen Server):

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

Wenn Sie die Datei direkt bearbeiten, starten Sie die Claude Code-Sitzung neu, um die Änderungen zu übernehmen.

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.

Docker

Ein Dockerfile ist für containerisierte Bereitstellungen und Glama-Kompatibilität enthalten.

Image bauen:

docker build -t mcp-hey .

Smoke-Test des Servers (sollte eine JSON-RPC-Antwort mit den verfügbaren Tools zurückgeben):

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | docker run -i mcp-hey

Hinweis: Das Docker-Image führt nur den MCP-Server aus. Der Python-Auth-Helfer und der Webview-Login sind innerhalb des Containers nicht verfügbar. Sie müssen bereits vorhandene Sitzungs-Cookies über ein Volume-Mount nach data/hey-cookies.json für authentifizierte Vorgänge bereitstellen.

macOS: bun PATH

GUI-Apps (Claude Desktop, Cursor) und Shells, die von Claude Code gestartet werden, erben nicht immer den PATH von Ihrem interaktiven Terminal. Daher kann ein über Homebrew installiertes bun mit spawn bun ENOENT fehlschlagen oder einfach nie eine Verbindung herstellen. Beheben Sie dies, indem Sie den absoluten Pfad zu bun im command verwenden:

• Apple Silicon Homebrew — /opt/homebrew/bin/bun

• Intel Homebrew — /usr/local/bin/bun

• Manuelle Installation — führen Sie which bun in Ihrem Terminal aus, um den Pfad zu finden

Beispiel:

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

Architektur

Datenfluss

1. Der MCP-Client (Claude Code, Claude Desktop, Cursor usw.) 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 einem 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 neues 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
      attachments.ts   # Download attachments, parse calendar invites
    __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 (33 tools)
    hey-features-doc.md  # Hey.com feature mapping

Verfügbare Tools

33 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, die mit 600-Berechtigungen geschrieben werden.

• 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 Dreiklang. 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 Vorwarnung ä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-Serverinstanz.

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

• Nur englische Benutzeroberfläche: Der Server parst die HTML-Antworten von Hey.com und gleicht englischsprachige Zeichenfolgen ab (z. B. "You ignored this thread", Label-Namen, Button-Text). Es wird nicht korrekt funktionieren, wenn Hey.com auf ein nicht-englisches Gebietsschema eingestellt ist.

Fehlerbehebung

• Auth-Webview öffnet sich nicht – bestätigen Sie, dass Python 3.10+ im PATH ist und uv 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 drosselt. Wenn Sie anhaltende 429er sehen, reduzieren Sie die gleichzeitige Tool-Nutzung oder warten Sie einige Minuten.

• MCP-Client kann den Server nicht starten – args muss ein absoluter Pfad sein, kein relativer. Wenn bun selbst mit spawn bun ENOENT fehlschlägt, siehe macOS: bun PATH.

• Cookie-Name geändert – Hey hat Sitzungs-Cookies bereits umbenannt (z. B. _hey_session → session_token, siehe docs/API.md Changelog). 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 (unterstützt durch Biome).

• Stellen Sie sicher, dass bun test besteht.

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

Siehe CLAUDE.md für den vollständigen Entwicklungsworkflow.

Lizenz

MIT-Lizenz – siehe LICENCE.