productivity-mcp

Lokaler Model Context Protocol-Server, der einem LLM-Client (Claude Desktop, Kiro, jede MCP-fähige App) Lese-/Schreibzugriff auf Ihre E-Mails und Kalender gewährt.

Unterstützt:

Läuft vollständig auf Ihrem Rechner über stdio. Es verlassen keine Daten Ihren Computer, außer an Ihre konfigurierten Mail-/Kalender-Server.

Installation

Erfordert macOS mit installiertem Homebrew. Alles andere (Python 3.13, uv, git) wird bei Bedarf installiert.

git clone https://github.com/seandkendall/productivity-mcp.git
cd productivity-mcp
./setup.sh

./setup.sh installiert fehlende Voraussetzungen via Homebrew, erstellt ein virtualenv, installiert das Paket und startet den interaktiven Konfigurationsassistenten.

Related MCP server: multi-mail-mcp

Konfiguration

Führen Sie den interaktiven Assistenten aus – er erstellt ein venv, installiert das Paket, fragt dann nach Ihren Anmeldedaten und schreibt die Konfiguration für Sie:

./setup.sh

Der Assistent unterstützt:

• iCloud / Apple Mail — E-Mail + app-spezifisches Passwort eingeben, fertig. Richtet sowohl Mail als auch Kalender ein.

• Gmail / Google Kalender — Verweisen Sie auf Ihre OAuth-Client-JSON (siehe unten, wie man eine erhält).

• Allgemeines IMAP — Wählen Sie eine Voreinstellung (Fastmail, Yahoo, Outlook) oder geben Sie einen benutzerdefinierten Host/Port ein.

Die Konfiguration wird mit 0600-Berechtigungen unter ~/.config/productivity-mcp/config.toml gespeichert. Führen Sie den Assistenten jederzeit erneut aus, um Konten hinzuzufügen oder zu ersetzen.

Gmail: Einmalige Google Cloud-Einrichtung

Google hat IMAP/SMTP-App-Passwörter im März 2025 deaktiviert, daher erfordert Gmail OAuth2. Vor dem Ausführen des Assistenten:

1. Öffnen Sie die Google Cloud Console → erstellen oder wählen Sie ein Projekt.

2. APIs & Dienste → Bibliothek → aktivieren Sie Gmail API und Google Calendar API.

3. APIs & Dienste → OAuth-Zustimmungsbildschirm → als Extern einrichten (fügen Sie sich selbst als Testnutzer hinzu).

4. Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID → Desktop-App → laden Sie die JSON herunter.

Führen Sie dann productivity-mcp setup aus, wählen Sie Gmail und verweisen Sie auf die heruntergeladene JSON. Der erste Tool-Aufruf öffnet einen Browser zur Autorisierung; das Refresh-Token wird lokal zwischengespeichert.

iCloud: Einmalige Apple ID-Einrichtung

Melden Sie sich unter appleid.apple.com an → Anmelden und Sicherheit → App-spezifische Passwörter → generieren Sie eines. Fügen Sie es bei Aufforderung in den Assistenten ein.

Manuelle Konfiguration (optional)

Wenn Sie TOML lieber direkt bearbeiten möchten, kopieren Sie example.config.toml nach ~/.config/productivity-mcp/config.toml.

Ausführung

productivity-mcp

Dies läuft über stdio – Sie binden es in einen Client ein, anstatt es als langlebigen Daemon auszuführen.

Claude Desktop

Bearbeiten Sie ~/Library/Application Support/Claude/claude_desktop_config.json:

{
 "mcpServers": {
 "productivity": {
 "command": "/absolute/path/to/.venv/bin/productivity-mcp"
 }
 }
}

Starten Sie Claude Desktop neu. Die Tools erscheinen unter dem 🔌-Menü.

Kiro

Fügen Sie in den Kiro-Einstellungen einen MCP-Server mit dem Befehl productivity-mcp (oder dem absoluten Pfad zum venv-Binary) hinzu. Er wird über stdio ausgeführt.

Verfügbare Tools (39)

Wenn account bei einem Tool weggelassen wird, wird das erste konfigurierte Konto dieses Typs verwendet. Siehe list_email_accounts / list_calendar_accounts, um Namen und Aliase zu entdecken.

E-Mail — Lesen & Entdecken

• list_email_accounts — konfigurierte Konten mit ihren addresses (primär + Aliase)

• list_folders(account?) — IMAP-Ordner / Gmail-Labels

• list_emails(account?, folder="INBOX", limit=25, query?, unread_only=false, recipients?, since_days?, senders?)

• read_email(message_id, account?, folder="INBOX", format="text"|"html"|"both") — HTML-Inhalte werden standardmäßig als Klartext gerendert

• search_threads(account?, folder="INBOX", query?, senders?, recipients?, since_days?, limit=25) — Deduplizierung nach Konversation

• search_emails_by_sender(senders, account?, folder="INBOX", since_days?, limit=25)

• count_emails(account?, folder="INBOX", query?, unread_only=false, senders?, recipients?, since_days?)

• count_unread(account?, folder="INBOX", since_days?)

• list_recent_senders(account?, folder="INBOX", since_days=30, top=20)

• summarize_inbox(account?, folder="INBOX", since_days=7, top=10) — Summen, Top-Absender, Top-Domains, Top-Empfänger-Aliase, Histogramm pro Tag

• resolve_contact(query, account?, limit=10) — Namens-/E-Mail-Suche (Gmail People API oder Scan aktueller Nachrichten)

E-Mail — Schreiben (ratenbegrenzt)

• send_email(to, subject, body, account?, cc?, bcc?, html=false)

• reply_email(message_id, body, reply_all=false, account?, folder="INBOX", html=false)

• forward_email(message_id, to, body="", account?, folder="INBOX", html=false)

• set_email_read(message_id, read=true, account?, folder="INBOX")

• delete_email(message_id, account?, folder="INBOX")

• move_email(message_id, target_folder, account?, folder="INBOX")

• bulk_set_read(message_ids, read=true, account?, folder="INBOX")

• bulk_delete_emails(message_ids, account?, folder="INBOX")

• bulk_move_emails(message_ids, target_folder, account?, folder="INBOX")

E-Mail — Entwürfe & Anhänge

• save_draft(to, subject, body, account?, cc?, bcc?, html=false)

• list_drafts(account?, limit=25)

• send_draft(draft_id, account?)

• list_attachments(message_id, account?, folder="INBOX")

• download_attachment(message_id, attachment_id, save_to?, account?, folder="INBOX") — auf Festplatte speichern oder base64 zurückgeben

Kalender

• list_calendar_accounts

• list_calendars(account?)

• list_events(account?, calendar?, start?, end?, limit=100) — standardmäßig die nächsten 7 Tage

• get_event(event_id, account?, calendar?)

• search_events(query, account?, calendar?, start?, end?, limit=50)

• create_event(summary, start, end, account?, calendar?, description?, location?, attendees?)

• update_event(event_id, account?, calendar?, summary?, start?, end?, description?, location?, attendees?)

• delete_event(event_id, account?, calendar?)

• respond_event(event_id, response, account?, calendar?) — accept | decline | tentative

• free_busy(start, end, account?, attendees?) — native Google freebusy.query; EWS/CalDAV greifen auf Ereignisaufzählung zurück

• suggest_meeting_times(duration_minutes, window_start, window_end, account?, attendees?, working_hours_start=9, working_hours_end=17, limit=5)

Aufgaben

• list_tasks(account?, limit=50) — Google Tasks (Google Kalender-Konten) oder EWS Tasks (WorkMail)

• create_task(title, account?, due?, notes?)

Diagnose

• ping(account?) — prüft jedes konfigurierte Konto; gibt {ok, latency_ms, error?} pro Konto zurück

Beobachtbarkeit

Jeder Tool-Aufruf sendet strukturiertes JSON an stderr:

{"ts":"...","level":"INFO","msg":"tool_call.start","tool":"list_emails","call_id":"b69185a6","arg_keys":["limit"]}
{"ts":"...","level":"INFO","msg":"tool_call.end","tool":"list_emails","call_id":"b69185a6","duration_ms":420}

Nur Argument-Schlüssel werden protokolliert – Werte werden niemals preisgegeben. Leiten Sie stderr beim Debuggen in eine Datei um.

Ratenbegrenzungen

Destruktive Tools haben weiche Ratenbegrenzungen, um versehentliche LLM-Schleifen einzudämmen. Standardwerte (pro Serverprozess, gleitendes Fenster):

Bei Überschreitung gibt das Tool einen RuntimeError mit der Wiederholungsverzögerung zurück. Starten Sie den Server neu, um ihn zurückzusetzen.

Entwicklung

# Lint
ruff check src tests
ruff format src tests

# Tests
pytest

Sicherheit

• Geheimnisse liegen in ~/.config/productivity-mcp/config.toml – werden niemals committet und nirgendwohin übertragen, außer an Ihre konfigurierten Mail-/Kalender-Server.

• Gmail OAuth-Token werden unter dem von Ihnen angegebenen token_file-Pfad zwischengespeichert; behandeln Sie diese wie Passwörter.

• Verwenden Sie für iCloud/IMAP immer app-spezifische Passwörter, niemals Ihr Hauptkontopasswort.

Lizenz

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• bulk_delete_emailsA
• bulk_move_emailsC
• bulk_set_readA
• count_emailsA
• count_unreadB
• create_eventC
• create_taskC
• delete_emailA