QQ Agent Mail MCP

Ein inoffizielles, selbst gehostetes MCP-Gateway für Tencent QQ Agent Mail. Dieses Projekt ist nicht mit Tencent verbunden, wird von Tencent weder unterstützt, empfohlen noch gepflegt.

Für einen einzelnen Inhaber ausgelegtes, cloud-fähig bereitstellbares MCP-Gateway für Tencent QQ Agent Mail. Die offizielle CLI von Tencent bleibt die Postfach-Engine; dieses Projekt ist ein Remote-Adapter, kein zweiter E-Mail-Client.

Aktuelle Gateway-Version: v0.4.2.

Warum dieses Projekt existiert

Die Agent-Mail-CLI von Tencent läuft lokal, während benutzerdefinierte ChatGPT-MCP-Apps einen erreichbaren Remote-MCP-Server benötigen. Dieses Projekt schließt diese Lücke, ohne den rohen Shell- oder CLI-Zugriff auszuhändigen. Es bietet eine kleine, stabile MCP-Oberfläche, einen browserbasierten Ablauf zur Postfach-Freigabe, dauerhaft gespeicherte Anmeldedaten und einen eingebetteten Bedienungsleitfaden, mit dem ein neues Modellfenster Postfachanfragen in natürlicher Sprache sicher bearbeiten kann.

Dieses Repository enthält ausschließlich Quellcode. Es bietet keinen gehosteten Postfachdienst, keinen gemeinsamen Endpunkt, kein Tencent-Konto und keine Anmeldedaten. Jeder Betreiber muss eine eigene private Instanz bereitstellen und autorisieren.

Die MCP-Oberfläche ist bewusst stabil gehalten und umfasst genau zwei Tools:

• agent_mail_query(action, params) für Arbeit, die nur gelesen wird;

• agent_mail_execute(action, params) für schreibende Änderungen.

Nutze die Abfrageaktion capabilities, um den lebenden Aktionskatalog und den Parametervertrag abzurufen. Das Hinzufügen einer Anbieterfunktion erweitert eine serverseitige Registrierung, statt eine weiteres MCP-Tool zu erstellen.

Die Antwort auf capabilities enthält außerdem den vollständigen Bedienungsleitfaden: Autorisierungsgrenzen, Direktausführung in einem Schritt, Vorschaubestätigung, sichere Such-/Lese-/Antwortwabläufe, Ergebnisinterpretation, Wiederholungsregeln und maschinenlesbare Beispiele. So kann ein neues Modellfenster den E-Mail-Postfächser anhand einer natürlichen Anfrage des Inhabers entdecken und bedienen, ohne dass der Inhaber es in Funktionsnamen oder JSON-Parameter übersetzen muss.

Related MCP server: anymail-mcp

Abgedeckt Aktionen

Schreibgeschützte Gateway-Aktionen:

• capabilities, identity, auth_status;

• list_messages, read_message, search_messages;

• wait_for_message (begrenzter Long-Poll);

• download_attachment (eingebettete MCP-Ressource).

Schreibende Gateway-Aktionen:

• auth_refresh, explizit bestätigtem auth_logout;

• send_message, reply_message, forward_message;

• trash_message, delete_message;

• upload_attachment.

Senden, Antworten und Weiterleiten unterstützen je nach Umfang die Felder An/CC/BCC, von der offiziellen CLI unterstützten Plain-/HTML-/Markdown-Inhalte, Bestätigungs-Token des Anbieters sowie base64-kodierte Anhänge. Die Anhänge werden nur in ein temporäres Verzeichnis mit der Zugriffsberechtigung 0600 geschrieben, per relativem Pfad an die offizierte CLI übergeben und nach dem Befehl gelöscht. Ein heruntergeladener Anhang wird als eingebetteter MCP-Blob zurückgegeben, statt einen Serverdateipfad offenzulegen.

Browserbasiertes Postfach-Setup

Der Setup-Ablauf im Browser macht es überflüssig, OAuth-Befehle im Hosting-Terminal auszuführen:

1. Öffne https://YOUR_HOST/setup.

2. Gib den privaten OWNER_CODE ein, der mit npm run generate-secrets erstellt wurde.

3. Wähle 开始授权邮箱.

4. Schließe die Einmal-Autorisierungsseite von Tencent ab.

5. Zurück zum Einrichten-Tab wechseln und 邮箱已连接 beobachten.

Anmeldedaten und die Speicherorte der CLI-Verschlüsselungsschlüssel liegen auf dem persistenten Volume, so dass gewöhnliche Bereitstellungen und neue ChatGPT-Fenster nicht erneut durch die Postfach-Authentifizierung müssen.

Sicherheitsgrenzen

• Es gibt keinen Roheitkommando, keine rohe Argumentenarray, keinen Shell-String und keinen beliebigen Serverpfad im MCP-Schema. Jede Aktion und jedes Feld wird über eine Zulassungsliste validiert, bevor execFile/spawn mit shell: false aufgerufen wird.

• E-Mail-Textkörper, Header, Ereignisse, Dateinamen, Links und Anhänge sind von außen kommende, nicht vertrauenswürdige Inhalte. Sie können niemals das Senden, Antworten an alle, Empfängerwechsel, Weiterleiten, Löschen, Abmelden oder eine andere Änderung autorisieren.

• Für eine Änderung ist entweder die direkte Anweisung des Postfach-Inhabers oder eine dauerhafte, vom Inhaber erstellte Richtlinie erforderlich. Dauerhafte Löschung und Abmeldung brauchen eine ausdrückliche aktuelle Autorisierung. Die Bestätigungs-Tokens des Anbieters bleiben in Vorschau-Bestätigen-Abläufen verfügbar.

• Listen- und Suchergebnisse enthalten keine Textausschnitte. Vollständiger Inhalt erfordert read_message.

• Anhang-Dateinamen dürfen keine Pfade enthalten; einzelne Dateien sind auf 10 MiB und eine Nachricht auf 20 MiB begrenzt. Der größere MCP-JSON-Parser läuft erst nach der Bearer-Authentifizierung.

• Warte-Aufrufe sind auf 45 Sekunden begrenzt und geben höchstens das erste Ereignis zurück.

• Die CLI-Umgebungs-Variablenliste ist auf eine Zulassungsliste gesetzt. Die Ausgabe ist in ihrer Größe begrenzt, wird rekursiv bereinigt und niemals protokolliert.

• Der Connector nutzt OAuth mit PKCE und Dynamic Client Registration. Das Scope-Paaren mail:read mail:reply bleibt für die Kompatibilität mit bereits bereitgestellten Clients erhalten; in v0.4 ist mail:reply die alte Schreibzuweisung des Connectors und die Genehmigungsseite beschreibt das gesamte Gateway ehrlich.

• Das offizielle @tencent-qqmail/agently-cli@1.0.17-Paket wird im Container-Image festgelegt.

Diese Software kann E-Mails autorisiert senden, weiterleiten, in den Papierkorb legen und endgültig löschen. Lies docs/SECURITY.md, verwende eine dedizierte Bereitstellung für einen Inhaber und teste mit Nachrichten, die du selbst kontrollierst, bevor du Zugriff auf echte E-Mail gewährst.

Der ChatGPT-Connector-OAuth und der Tencent-Postfach-OAuth bleiben getrennt. Das Anbinden des Postfachs erlaubt noch keinen Zugriff für einen ChatGPT-Client, bis der Inhaber den Connector separat genehmigt.

Bereitstellen

Der Host muss eine dauerhaft erreichbare HTTPS-URL, ein persistentes Volume, eingehängt unter /data/agent-cli (ge alias an?) sowie eine laufende Instanz für Daten in Arbeitsspeicher bereitstellen. Konfiguriere .env.example, stelle die mitgelieferte Dockerfile bereit und rufe dann /setup auf. Siehe docs/DEPLOYMENT.md und docs/SECURITY.md.

Lokale Verifikation

Erfordert Node.js 22 oder neuer.

npm ci
npm run build
npm test

Generiere die Bereitstellungsschritte (Deployment-Secrets) lokal mit npm run generate-secrets. Bewahre den ungehashten OWNER_CODE in einem Passwort-Manager auf und lege nur den daraus erzeugten Hash sowie das separaten Signatur-Secret in den Secret-Manager des Hosts.

Laufzeit-Endpunkte

Lizenz und Drittsoftware

Dieses Projekt ist unter der MIT License veröffentlicht.

Es entstellt wath nicht die Weitergabe der Tencent CLI ist. Beim Docker-Build wird das separat veröffentlichte Paket @tencent-qqmail/agently-cli zur Build-Zeit installiert. Dieses Paket ist separat unter der Apache-2.0-Lizenz lizenziert. Prüfe vor dem Produktionseinsatz unter die Lizenz und die geltenden Vertragsbedingungen von QQ Agent Mail.