MailCal

Lokaler E-Mail-Kalender-Manager: Liest E-Mails über IMAP, bereinigt automatisch Vorstellungsgespräche, Assessments, Besprechungen und Fristen aus E-Mails zu Kalenderereignissen, bietet eine HTML-Kalenderoberfläche und stellt gleichzeitig REST-API und MCP für Tools wie Codex bereit.

Blog-Tutorial

Ausführliches Tutorial: Selbstrettungsleitfaden für den Herbst: Mit MailCal das QQ-Postfach in einen AI-Kalender verwandeln, Vorstellungsgespräche und Assessments automatisch in den Zeitplan aufnehmen

QQ-Postfach-Autorisierungscode-Konfiguration: QQ-Postfach-IMAP-Konfigurationsanleitung

Open Source und Kontakt

MailCal ist Open Source, Feedback als Star und Issue ist willkommen.

• GitHub-Repository: GlenYe-Coding/MailCal

• QQ-Gruppe: 686046608 · Klicken Sie, um der MailCal-Gruppe beizutreten

Funktionen

• Inkrementelle E-Mail-Synchronisierung: Verwendet einen UID-Cursor zur Speicherung der Synchronisationsposition, verarbeitet nur neue E-Mails

• E-Mail-Bereinigung: HTML in reinen Text umwandeln, Skripte und Stile entfernen, Links für die Analyse behalten

• Ereignisextraktion: Regel-Engine + LangGraph-Agent entscheidet, ob eine E-Mail eine Aufgabe erzeugen soll

• Kalenderoberfläche: Monatsansicht / Wochenansicht, Ereignisstatus, Hover-Zusammenfassung, Original-E-Mail-Rendering

• Admin-Konsole: Protokolle, Token-Verbrauch, E-Mail-Statistiken, Cache-Bereinigung

• Doppelte Schnittstelle: REST-API + MCP, unterstützt lokalen Dienst oder Codex-Anbindung

• Modellunterstützung: OpenAI, DeepSeek, Kimi, GLM, Qwen, SiliconFlow, Ollama, benutzerdefinierte OpenAI-kompatible Dienste

Dokumentation

• Dokumentationsindex: Einstieg in alle MailCal-Dokumente

• API-Dokumentation: REST-Schnittstellen, Anfrageparameter, Antwortformate, Fehlerbeschränkungen

• MCP-Dokumentation: MCP-Tools, Parameterbeschränkungen, Codex-Anbindung

• Architekturdokumentation: Systemübersicht, Synchronisationspipeline, Zustandsmaschine

• Konfigurationsdokumentation: config.json, Umgebungsvariablen, Cache- und Modellkonfiguration

• Bereinigungsworkflow: Standardisierter Verarbeitungsprozess von E-Mails zu Ereignissen

• JSON-Schema: Bereinigte E-Mails, Ereignisse, Modellausgabeformate

Projektstruktur

MailCal/
├─ src/        后端源码
├─ static/     前端页面、样式、脚本、图片
├─ tests/      单元测试
├─ schemas/    JSON Schema
├─ docs/       全部文档与截图（含文档索引）
├─ scripts/    启动脚本
├─ data/       事件、游标、用量数据
├─ logs/       运行日志
└─ config.json 本地配置

Schnellstart

cd D:/Project/MailCal
python src/app.py --host 127.0.0.1 --port 5173

Öffnen Sie http://127.0.0.1:5173, um die Kalenderoberfläche zu verwenden.

Beim ersten Start wird automatisch config.json erstellt; Sie können auch config.example.json kopieren und manuell den E-Mail-Autorisierungscode und die Modellkonfiguration ausfüllen.

Unter Windows können Sie direkt scripts/start.bat oder scripts/start.ps1 ausführen.

REST-API

Vollständige Parameterbeschränkungen finden Sie in docs/API.md.

MCP

python src/mcp_server.py

Codex-Anbindung:

codex mcp add mailcal -- python D:/Project/MailCal/src/mcp_server.py

HTTP-Modus:

python src/mcp_server.py --http --port 5174

Verbindungsadresse: http://127.0.0.1:5174/mcp

Verfügbare Tools: list_events, get_event, sync_emails, list_models, get_status, reset_sync_cursor, get_usage, reset_usage, add_event, update_event, delete_event.

Vollständige Parameterbeschränkungen finden Sie in docs/MCP.md.

Konfiguration

Die Konfigurationsdatei ist config.json und unterstützt die Überschreibung durch Umgebungsvariablen. Der E-Mail-Autorisierungscode und der Modell-API-Schlüssel erscheinen in den Schnittstellenantworten nur maskiert.

Detaillierte Felder finden Sie in docs/CONFIGURATION.md, die Liste der Umgebungsvariablen in .env.example.

Sicherheitshinweise

• Standardmäßig wird nur auf 127.0.0.1 gehört, nicht öffentlich zugänglich

• Bitte keine Schlüssel aus config.json, .env oder Protokollen in das Code-Repository committen

• Die sid einer einzelnen E-Mail im QQ-Webmailer verfällt mit dem Anmeldestatus; die Ereignisdetails bieten zwei zuverlässige Einstiege: „QQ-Postfach öffnen“ und „Original-E-Mail herunterladen“

Tests

python -m unittest discover -s tests -v