JMAP MCP Server

Ein Model Context Protocol (MCP) Server, der Tools für die Interaktion mit JMAP (JSON Meta Application Protocol) E-Mail-Servern bereitstellt. Erstellt mit Deno und unter Verwendung der @htunnicliff/jmap-jam Client-Bibliothek.

Funktionen

E-Mail-Verwaltungstools

• E-Mails suchen: Suchen Sie E-Mails mit Textabfragen, Absender-/Empfängerfiltern, Datumsbereichen und Schlüsselwörtern. Alle Filter werden mit UND verknüpft.

• E-Mails abrufen: Rufen Sie bestimmte E-Mails nach ID mit konfigurierbarer Eigenschaftsauswahl ab

• Threads abrufen: Rufen Sie E-Mail-Threads (Konversationsketten) ab

• E-Mails markieren: Markieren Sie E-Mails als gelesen/ungelesen, markiert/nicht markiert

• E-Mails verschieben: Verschieben Sie E-Mails zwischen Postfächern

• E-Mails löschen: Löschen Sie E-Mails dauerhaft

Postfachverwaltung

• Postfächer abrufen: Listen Sie alle Postfächer/Ordner mit Hierarchieunterstützung auf. Verwenden Sie dies, um Postfach-IDs zu finden, die von anderen Tools benötigt werden.

Inkrementelle Synchronisierung

• E-Mail-Änderungen abrufen: Rufen Sie IDs von E-Mails ab, die seit einem vorherigen Status erstellt, aktualisiert oder gelöscht wurden (zustandsbasierte Delta-Verfolgung)

• Suchaktualisierungen abrufen: Rufen Sie Ergänzungen/Entfernungen innerhalb einer vorherigen Suchabfrage seit deren letztem queryState ab

E-Mail-Erstellung

• E-Mail senden: Verfassen und senden Sie neue E-Mails mit Unterstützung für Klartext und HTML

• Auf E-Mail antworten: Antworten Sie auf bestehende E-Mails mit automatischer Header-Verarbeitung und Unterstützung für „Allen antworten“

Hauptfunktionen

• Vollständige JMAP RFC 8620/8621-Konformität via jmap-jam

• Umfassende Eingabevalidierung mit Zod-Schemas

• Paginierungsunterstützung für alle Listenoperationen

• Zustandsbasierte inkrementelle Synchronisierung für effizientes Polling

• Umfassende Fehlerbehandlung und Verbindungsverwaltung

• Fähigkeitsbasierte Tool-Registrierung (schreibgeschützt, Übermittlung)

• TypeScript-Unterstützung mit starker Typisierung

Related MCP server: bare-mcp

Installation

Claude Code Plugin (Empfohlen)

Installation über den Plugin-Marktplatz:

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

Konfigurieren Sie dann die erforderlichen Umgebungsvariablen in Ihren MCP-Servereinstellungen.

Voraussetzungen

• Deno v1.40 oder neuer

• Ein JMAP-konformer E-Mail-Server (z. B. Cyrus IMAP, Stalwart Mail Server, FastMail)

• Gültige JMAP-Authentifizierungsdaten

Einrichtung

Fügen Sie Folgendes zu Ihrem bevorzugten Agenten hinzu:

{
  "mcpServers": {
    "jmap": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.3"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Ersetzen Sie api.fastmail.com in --allow-net durch den Hostnamen Ihres JMAP-Servers, falls Sie nicht FastMail verwenden.

Verwendung

Umgebungsvariablen

Verfügbare Tools

get_mailboxes

Listen Sie Postfächer/Ordner mit ihren IDs, Namen und Metadaten auf. Rufen Sie dies zuerst auf, um Postfach-IDs zu erhalten, die für search_emails (inMailbox) und move_emails (mailboxId) benötigt werden. Häufige Namen: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.

Parameter:

• parentId (optional): Filtern nach übergeordneter Postfach-ID

• limit (optional): Maximale Ergebnisse (1-200, Standard: 100)

• position (optional): Startposition für die Paginierung

search_emails

Suchen Sie E-Mails mit Filtern. Alle Filter werden mit UND verknüpft. Gibt nur E-Mail-IDs zurück — verwenden Sie get_emails, um den Inhalt abzurufen. Die Ergebnisse enthalten queryState für die inkrementelle Synchronisierung via get_search_updates.

Parameter:

• query (optional): Textsuche über alle Felder

• body (optional): Suche nur im Nachrichtentext

• from (optional): Filtern nach Absender-E-Mail-Adresse

• to (optional): Filtern nach Empfänger-E-Mail-Adresse

• subject (optional): Filtern nach Betrefftext

• inMailbox (optional): Postfach-ID, in der gesucht werden soll (erhalten über get_mailboxes)

• hasKeyword (optional): Filtern nach Schlüsselwort (z. B. $seen, $flagged)

• notKeyword (optional): Ausschließen nach Schlüsselwort (z. B. $seen, $draft)

• allInThreadHaveKeyword (optional): Alle E-Mails im Thread müssen das Schlüsselwort haben

• someInThreadHaveKeyword (optional): Mindestens eine E-Mail im Thread muss das Schlüsselwort haben

• before (optional): Nur E-Mails vor dem Datum (ISO 8601 Datum/Uhrzeit)

• after (optional): Nur E-Mails nach dem Datum (ISO 8601 Datum/Uhrzeit)

• limit (optional): Maximale Ergebnisse (1-100, Standard: 50)

• position (optional): Startposition für die Paginierung (Standard: 0)

get_emails

Abrufen spezifischer E-Mails anhand ihrer IDs. Verwenden Sie properties, um nur das anzufordern, was Sie benötigen — das Abrufen aller Eigenschaften führt zu großen Payloads.

Parameter:

• ids: Array von E-Mail-IDs (1-50 IDs)

• properties (optional): Spezifische Eigenschaften, die zurückgegeben werden sollen. Empfohlene Sets:

• Zusammenfassung: ["id", "subject", "from", "to", "receivedAt", "preview"]

• Vollständig gelesen: ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]

• Hinweis: Um den Textinhalt zu erhalten, fügen Sie bodyValues UND textBody/htmlBody hinzu

get_threads

Abrufen von E-Mail-Threads anhand ihrer IDs. Thread-IDs stammen aus get_emails-Antworten (threadId-Eigenschaft). Gibt E-Mail-IDs pro Thread zurück — verwenden Sie get_emails für diese IDs, um den Inhalt abzurufen.

Parameter:

• ids: Array von Thread-IDs (1-20 IDs)

get_email_changes

Abrufen von IDs von E-Mails, die seit einem vorherigen Status erstellt, aktualisiert oder gelöscht wurden. Verwenden Sie den state-String aus einer get_emails-Antwort.

Parameter:

• sinceState: State-String aus einer vorherigen get_emails-Antwort

• maxChanges (optional): Maximale Änderungen, die zurückgegeben werden sollen (1-500)

• fetchEmails (optional): Automatisches Abrufen vollständiger E-Mail-Details für geänderte IDs (Standard: false)

• properties (optional): Eigenschaften, die abgerufen werden sollen, wenn fetchEmails wahr ist

get_search_updates

Abrufen von Änderungen innerhalb einer vorherigen Suchabfrage seit deren queryState. Muss dieselben Filterparameter wie der ursprüngliche search_emails-Aufruf verwenden.

Parameter:

• sinceQueryState: queryState aus einer vorherigen search_emails-Antwort

• Alle Filterparameter von search_emails (müssen mit der ursprünglichen Abfrage übereinstimmen)

• maxChanges (optional): Maximale Änderungen, die zurückgegeben werden sollen (1-500)

mark_emails

Markieren Sie E-Mails als gelesen/ungelesen oder markiert/nicht markiert.

Parameter:

• ids: Array von E-Mail-IDs (1-100 IDs)

• seen (optional): Als gelesen (true) oder ungelesen (false) markieren

• flagged (optional): Als markiert (true) oder nicht markiert (false) markieren

move_emails

Verschieben Sie E-Mails in ein anderes Postfach. Verwenden Sie get_mailboxes, um die Ziel-Postfach-ID zu finden.

Parameter:

• ids: Array von E-Mail-IDs (1-100 IDs)

• mailboxId: Ziel-Postfach-ID (erhalten über get_mailboxes)

delete_emails

Löschen Sie E-Mails dauerhaft (kann nicht rückgängig gemacht werden). Bevorzugen Sie das Verschieben in den Papierkorb via move_emails für eine wiederherstellbare Löschung.

Parameter:

• ids: Array von E-Mail-IDs (1-100 IDs)

send_email

Senden Sie eine neue E-Mail. Erfordert entweder textBody oder htmlBody (oder beides).

Parameter:

• to: Array von Empfängern (name optional, email erforderlich)

• cc (optional): Array von CC-Empfängern

• bcc (optional): Array von BCC-Empfängern

• subject: E-Mail-Betreff

• textBody (optional): Klartext-Body

• htmlBody (optional): HTML-Body

• identityId (optional): JMAP-Identitäts-ID, von der aus gesendet werden soll (verwendet den Server-Standard, falls weggelassen)

reply_to_email

Antworten Sie auf eine bestehende E-Mail. Setzt automatisch To/CC, Re:-Betreff-Präfix und Threading-Header (In-Reply-To, References).

Parameter:

• emailId: ID der E-Mail, auf die geantwortet werden soll

• replyAll (optional): Alle ursprünglichen Empfänger einbeziehen (Standard: false)

• subject (optional): Benutzerdefinierter Antwortbetreff (Standard: Re: <original>)

• textBody (optional): Klartext-Body

• htmlBody (optional): HTML-Body

• identityId (optional): JMAP-Identitäts-ID, von der aus gesendet werden soll (verwendet den Server-Standard, falls weggelassen)

JMAP-Server-Kompatibilität

Dieser Server sollte mit jedem JMAP-konformen E-Mail-Server funktionieren, einschließlich:

• Cyrus IMAP 3.0+

• Stalwart Mail Server

• FastMail (kommerziell)

• Apache James (mit JMAP-Unterstützung)

Entwicklung

Ausführung in der Entwicklung

just watch          # Run with file watching
just start          # Run without watching

Testen

just test           # Run all tests
just check          # Format check + lint + type check
just fmt            # Auto-format code

Architektur

Der Server wurde erstellt mit:

• Deno: Moderne JavaScript/TypeScript-Laufzeitumgebung

• @modelcontextprotocol/sdk: MCP-Server-Framework

• jmap-jam: Leichtgewichtiger, typisierter JMAP-Client

• Zod: Laufzeit-Typvalidierung

Sicherheit

• Alle Eingaben werden mit Zod-Schemas validiert

• Umgebungsvariablen werden für sensible Konfigurationen verwendet

• Keine Geheimnisse werden protokolliert oder in Antworten offengelegt

• Befolgt JMAP-Sicherheits-Best-Practices

Mitwirken

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch

3. Nehmen Sie Änderungen gemäß dem funktionalen Programmierstil vor

4. Testen Sie Ihre Änderungen gründlich

5. Senden Sie einen Pull Request

Lizenz

MIT-Lizenz - siehe LICENSE-Datei für Details.

Verwandte Projekte

• jmap-jam - JMAP-Client-Bibliothek

• Model Context Protocol - MCP-Spezifikation

• JMAP RFC 8620 - JMAP-Kernprotokoll

• JMAP RFC 8621 - JMAP für Mail