personal-mail-mcp

Lokaler MCP-Server für den Zugriff von Codex auf persönliche E-Mail- und Kalenderkonten.

Er verbindet Codex mit Microsoft Graph und Gmail, sodass ein lokaler Assistent den Posteingang überprüfen, nach Terminbestätigungen suchen, Kalendereinträge erstellen oder aktualisieren, ungelesene E-Mails finden, die außerhalb des Posteingangs übersehen wurden, und sichere Archivierungspläne für weniger wichtige Nachrichten erstellen kann. Das Projekt enthält auch Codex-Skills für wiederkehrende Arbeitsabläufe wie Termin-Erfassung, Posteingangs-Triage, Überprüfung verpasster E-Mails und vollständige E-Mail-Durchsicht.

Dieses Projekt wird "wie besehen" bereitgestellt. Es funktioniert für mein eigenes Setup, wurde jedoch nicht umfassend für andere Konten, Mandanten, E-Mail-Anbieter oder Outlook/Gmail-Konfigurationen getestet.

Aktuelles Ziel:

• GoDaddy-gehostete Exchange-Postfächer und Kalender über Microsoft Graph.

• Gmail über Google APIs.

• Nur-Lese-Audit-/Planungstools sowie explizite Archivierungs- und Kalender-Schreib-Tools.

Es sollten keine OAuth-Geheimnisse oder Token-Caches committet werden. Kopieren Sie config/accounts.example.toml nach config/accounts.toml für lokale Einstellungen. Kopieren Sie config/auth.example.toml nach config/auth.toml für OAuth-App-Einstellungen. Halten Sie lokale Konfigurationsdateien für Ihr Benutzerkonto privat.

Empfohlene Berechtigungen für lokale Dateien:

chmod 700 .private .tokens
chmod 600 config/accounts.toml config/auth.toml config/mail_rules.local.toml

Lokale Projekteinrichtung

Erstellen und installieren Sie die lokale Umgebung:

cd <repo-path>
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[providers]'

Codex-Konfiguration

Fügen Sie den MCP-Server zu ~/.codex/config.toml hinzu:

[mcp_servers.personal_mail]
type = "stdio"
command = "<repo-path>/.venv/bin/python"
args = ["-m", "personal_mail_mcp.server"]
startup_timeout_sec = 30

Starten Sie Codex nach dem Ändern der Konfiguration neu, damit der MCP-Server in der Liste der aktiven Tools erscheint.

Kontokonfiguration

Erstellen Sie config/accounts.toml:

[[accounts]]
id = "exchange_primary"
provider = "microsoft"
email = "primary@example.com"
calendar = true

[[accounts]]
id = "exchange_secondary"
provider = "microsoft"
email = "secondary@example.com"
calendar = false

[[accounts]]
id = "google_primary"
provider = "google"
email = "public-example@gmail.com"
calendar = false

Diese Datei wird von git ignoriert.

Microsoft-App-Registrierung

Die GoDaddy-Konten sind Exchange Online-Konten, die über Microsoft Graph erreichbar sind. Es ist keine GoDaddy-spezifische API erforderlich.

1. Öffnen Sie das Microsoft Entra Admin Center:

   https://entra.microsoft.com/

2. Gehen Sie zu:

   Entra ID > App registrations > New registration

   Wenn die linke Navigation anders aussieht, suchen Sie im Suchfeld des Portals nach App-Registrierungen.

3. Registrieren Sie die App:

   Name: personal-mail-mcp
   Supported account types: Single tenant only - your Microsoft 365 tenant

4. Kopieren Sie auf der Übersichtsseite der App-Registrierung:

   Application (client) ID
   Directory (tenant) ID

5. Fügen Sie unter Authentifizierung eine Umleitungs-URL für eine native/lokale App hinzu:

   http://localhost

   Dies erscheint in der aktuellen Portal-UI unter Mobile und Desktop-Anwendungen / Umleitungs-URLs.

6. Aktivieren Sie unter Authentifizierungseinstellungen öffentliche/native Client-Flows. Die Portal-Formulierung kann eine der folgenden sein:

   Allow public client flows
   Enable the following mobile and desktop flows
   Treat application as a public client

   Setzen Sie sie auf Ja und speichern Sie.

7. Fügen Sie unter API-Berechtigungen delegierte Microsoft Graph-Berechtigungen hinzu:

   Mail.Read
   Mail.ReadWrite
   Calendars.ReadWrite
   offline_access

Erstellen Sie config/auth.toml mit den kopierten IDs:

[microsoft]
client_id = "APPLICATION_CLIENT_ID_FROM_ENTRA"
tenant = "DIRECTORY_TENANT_ID_FROM_ENTRA"

[google]
client_secrets_file = ".private/google-oauth-client.json"

Speichern Sie keine OpenAI-, ChatGPT-, Codex- oder GitHub-Token in dieser Datei. Diese Datei wird von git ignoriert.

Exchange Online-Konten verbinden

cd <repo-path>
.venv/bin/python -m personal_mail_mcp.cli status
PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect exchange_primary
PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect exchange_secondary

Jeder Verbindungsbefehl gibt eine Microsoft-Gerätecode-URL und einen Code aus. Öffnen Sie die URL, geben Sie den Code ein und melden Sie sich mit dem entsprechenden Konto an:

exchange_primary   -> primary Exchange Online mailbox
exchange_secondary -> secondary Exchange Online mailbox

Erfolgreiche Verbindungen schreiben lokale Token-Cache-Dateien unter .tokens/, was von git ignoriert wird.

Überprüfung:

.venv/bin/python -m personal_mail_mcp.cli status

Die Microsoft-Konten sollten anzeigen:

token_cached: true

Nur-Lese-Überprüfung

Abrufen der letzten fünf Nachrichtenbetreffzeilen aus dem Exchange-Hauptpostfach:

.venv/bin/python -m personal_mail_mcp.cli recent-messages exchange_primary --limit 5

Das entsprechende MCP-Tool, das Codex zur Verfügung gestellt wird, ist:

microsoft_recent_messages(account_id, limit=5)

Gmail-Einrichtung

Verwenden Sie ein Google Cloud-Projekt für die Gmail-API und OAuth-Desktop-Anmeldeinformationen.

1. Öffnen Sie die Google Cloud Console:

   https://console.cloud.google.com/

2. Erstellen oder wählen Sie ein Projekt und aktivieren Sie dann:

   Gmail API

3. Konfigurieren Sie die OAuth-Zustimmung unter:

   Google Auth Platform > Branding

   Verwenden Sie einen einfachen App-Namen wie personal-mail-mcp. Verwenden Sie für persönliche Gmail-Konten die Zielgruppe Extern und fügen Sie Ihre Gmail-Adresse als Testbenutzer hinzu unter:

   Google Auth Platform > Audience > Test users

4. Erstellen Sie einen Desktop-OAuth-Client unter:

   Google Auth Platform > Clients > Create client

   Verwenden Sie:

   Application type: Desktop app
   Name: personal-mail-mcp

5. Laden Sie das OAuth-Client-JSON herunter und speichern Sie es lokal:

   <repo-path>/.private/google-oauth-client.json

   Verschärfen Sie die Berechtigungen:

   chmod 600 .private/google-oauth-client.json

6. Stellen Sie sicher, dass config/auth.toml auf die Datei verweist:

   [google]
   client_secrets_file = ".private/google-oauth-client.json"

7. Verbinden Sie das Gmail-Konto:

   cd <repo-path>
   PYTHONUNBUFFERED=1 .venv/bin/python -m personal_mail_mcp.cli connect google_primary

   Öffnen Sie die ausgegebene Google-URL, melden Sie sich mit dem konfigurierten Testbenutzer an und genehmigen Sie die Gmail-Lese-/Änderungsbereiche.

8. Überprüfung:

   .venv/bin/python -m personal_mail_mcp.cli status

   Das Gmail-Konto sollte anzeigen:

token_cached: true

Abrufen der letzten drei Gmail-Posteingangsbetreffzeilen:

.venv/bin/python -m personal_mail_mcp.cli recent-gmail google_primary --limit 3

Das entsprechende MCP-Tool, das Codex zur Verfügung gestellt wird, ist:

gmail_recent_messages(account_id, limit=5)

E-Mail-Triage

Der MCP-Server enthält wiederverwendbare Posteingangs-Audit- und Archivierungshelfer, sodass für wiederholte Triage keine Ad-hoc-Skripte erforderlich sind.

Führen Sie ein Nur-Lese-Audit über Konten hinweg durch:

cd <repo-path>
.venv/bin/python -m personal_mail_mcp.cli audit-mail exchange_primary exchange_secondary google_primary --limit-per-account 250

Erstellen Sie einen Trockenübungs-Archivierungsplan. Dies gibt nur Archivierungskandidaten zurück, gruppiert über alle angeforderten Konten nach Archivierungsgrund, Absender und normalisiertem Betreff. Jede Nachricht enthält ihre Konto-ID, Nachrichten-ID, Betreff, Absender und Empfangsdatum:

.venv/bin/python -m personal_mail_mcp.cli archive-plan exchange_primary exchange_secondary google_primary --limit-per-account 250

Listen Sie einen einzelnen Posteingang mit Paginierung auf:

.venv/bin/python -m personal_mail_mcp.cli inbox exchange_primary --limit 100

Suchen Sie nach ungelesenen E-Mails außerhalb des Posteingangs, wie z. B. archivierten oder durch Regeln verschobenen Nachrichten. Der Befehl klassifiziert diese Nachrichten und gibt Aufmerksamkeitskandidaten getrennt von offensichtlichem Archiv/Rauschen zurück:

.venv/bin/python -m personal_mail_mcp.cli missed-mail exchange_primary exchange_secondary google_primary --limit-per-account 100

Archivieren Sie ausgewählte Nachrichten nach ID:

.venv/bin/python -m personal_mail_mcp.cli archive-mail exchange_primary <message-id> [<message-id> ...]

Die entsprechenden MCP-Tools, die Codex zur Verfügung gestellt werden, sind:

mail_inbox(account_id, limit=100)
mail_audit(account_ids, limit_per_account=250)
mail_archive_plan(account_ids, limit_per_account=250)
missed_mail(account_ids, limit_per_account=100)
archive_messages(account_id, message_ids)

Der Audit-Klassifikator ist absichtlich deterministisch. Er gruppiert E-Mails in keep, flag, archive und review. Verwenden Sie mail_archive_plan als normalen Überprüfungsschritt, bevor Sie Nachrichten verschieben; er ist schreibgeschützt und enthält die genauen IDs, die für archive_messages benötigt werden. Wenn dasselbe Archivierungsmuster mehr als einmal oder über mehrere Konten hinweg erscheint, gibt der Plan auch Filterempfehlungen zurück, die verwendet werden können, um Postfach-/Anbieterregeln für zukünftige Nachrichten zu erstellen.

Die Erstellung von Remote-Filtern/Regeln ist möglich, erfordert jedoch zusätzliche OAuth-Bereiche: Microsoft Graph-Nachrichtenregeln erfordern MailboxSettings.ReadWrite; die Erstellung von Gmail-Filtern erfordert gmail.settings.basic. Bis diese hinzugefügt und genehmigt wurden, sollte der Server Filter nur empfehlen, anstatt sie zu erstellen.

Wiederverwendbare Standardeinstellungen befinden sich in config/mail_rules.default.toml. Benutzerspezifische Absender, Aufbewahrungsanzahlen und Archivierungsmuster gehören in config/mail_rules.local.toml, das von git ignoriert wird. Verwenden Sie config/mail_rules.example.toml als Vorlage für lokale Überschreibungen.

Optionaler Codex-Skill

Dieses Projekt enthält einen gemeinsam nutzbaren Codex-Skill:

skills/email-appointment-harvest
skills/inbox-triage
skills/missed-mail-review
skills/review-all-mail

Der Skill dokumentiert den wiederholbaren Arbeitsablauf zum Scannen aktueller E-Mails, zum Vorschlagen von Termin-/Kalenderkandidaten, zum Warten auf Genehmigung und zum anschließenden Erstellen oder Aktualisieren nur genehmigter Kalendereinträge.

Installieren Sie ihn in einer Codex-Umgebung:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/email-appointment-harvest "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/inbox-triage "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/missed-mail-review "${CODEX_HOME:-$HOME/.codex}/skills/"
cp -R skills/review-all-mail "${CODEX_HOME:-$HOME/.codex}/skills/"

Starten Sie Codex nach der Installation neu. Beispielanfrage:

Use email appointment harvest to scan the last 7 days of email for appointments,
propose calendar entries, and add only the entries I approve.

Der installierte Skill setzt voraus, dass dieser MCP-Server in Codex konfiguriert ist und dass die E-Mail-/Kalender-OAuth-Token bereits verbunden wurden.

Sicherheitshinweise

• config/auth.toml, config/accounts.toml und .tokens/ sind nur lokal vorhanden.

• Die Microsoft-App ist ein öffentlicher/nativer Client; erstellen oder speichern Sie kein Client-Geheimnis für diesen CLI-Flow.

• Gmail-Client-Anmeldeinformationen unter .private/ und Token-Caches unter .tokens/ sollten den Modus 600 für Dateien und 700 für Verzeichnisse haben.

• Microsoft Mail.ReadWrite, Google gmail.modify und Microsoft Calendars.ReadWrite sind für die aktuellen Archivierungs-/Kalender-Tools erforderlich. Halten Sie die App-Registrierung auf die von Ihnen verwendeten delegierten Berechtigungen beschränkt.

• Behandeln Sie archive_messages und Kalender-Mutationstools als Schreibaktionen. Bevorzugen Sie mail_archive_plan und Kalender-Lesevorgänge, bevor Sie Änderungen anwenden.

• Rotieren Sie alle persönlichen Zugriffstoken, die jemals in einer Klartext-Konfiguration gespeichert wurden.