TimeTree MCP

TimeTree MCP ist ein inoffizieller Model Context Protocol-Server, der über HTTPS auf TimeTree-Kalender zugreift. Standardmäßig wird der Python-Directclient verwendet; es wird kein Browser gestartet. Der Browser-Transport bleibt nur als Kompatibilitäts-Backup erhalten. Session-Cookies und CSRF-Token werden nur im Speicher des MCP-Prozesses gehalten.

Wichtig: Die offizielle TimeTree Connect-App/API wurde eingestellt. Dieses Projekt nutzt einen nicht öffentlichen Endpoint von TimeTree Web und kann bei Änderungen des Dienstes unbrauchbar werden. Bitte bewerten Sie die Risiken selbst und befolgen Sie die Bedingungen und Richtlinien von TimeTree.

Funktionen

• Liest Kalender, Events, Memos, Kommentare, Labels und Mitglieder.

• Erstellt, aktualisiert und löscht Events und Memos.

• Fügt Event-Kommentare hinzu, aktualisiert und löscht sie.

• Aktualisiert Kalender-Labels per Merge.

• Überwacht Kalenderänderungen im Hintergrund und sendet MCP-Benachrichtigungen.

• Alle Schreiboperationen erfordern die explizite Übergabe von confirm: true.

• Credentials werden nicht als MCP-Toolargumente übergeben; die authentifizierte Sitzung wird nur im Speicher gehalten.

Related MCP server: TimeTree MCP Server

Voraussetzungen

• Python 3.10 oder höher.

• Ein TimeTree-Konto.

• macOS ist für den Keychain-Helfer erforderlich; andere Plattformen können Umgebungsvariable oder eine Passwortdatei nutzen.

Installation

git clone <repository-url>
cd timetree-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --editable .

Die Laufzeitumgebung verwendet ausschließlich die Python-Standardbibliothek. Nach der Installation stehen die Befehle timetree-mcp und timetree-credentials zur Verfügung.

Mit dem NPM wrapper

Der NPM wrapper erfordert Node.js 18+ und Python 3.10+; er startet den im Paket enthaltenen Python-MCP-Server und leitet das MCP-Stdin/stdout weiter:

npx --yes timetree-mcp

Es kann auch global installiert werden:

npm install --global timetree-mcp
timetree-mcp

Zugangsdaten konfigurieren

Für macOS wird die Verwendung von Keychain empfohlen. Bei der Einrichtung wird das Passwort nur verdeckt im Terminal eingegeben und gelangt nicht in die Shell-History, die MCP-Toolargumente oder den Quellcode:

./scripts/setup_timetree_keychain.sh
timetree-credentials status

Der MCP liest die E-Mail-Adresse beziehungsweise das Passwort automatisch aus Keychain. Der Status meldet nur, ob sie vorhanden sind, und gibt die Werte nicht zurück. Beide Keychain-Einträge löschen:

timetree-credentials clear

Ohne Keychain können auch Umgebungsvariablen verwendet werden:

export TIMETREE_EMAIL='your-email@example.com'
export TIMETREE_PASSWORD='your-password'

Noch besser ist einer Passwortdatei mit den Berechtigungen 600:

chmod 600 /absolute/path/to/timetree-password
export TIMETREE_EMAIL='your-email@example.com'
export TIMETREE_PASSWORD_FILE='/absolute/path/to/timetree-password'

Registrierung in Codex

Ersetzen Sie /absolute/path/to/timetree-mcp durch den Checkout-Pfad. Falls bereits ein gleichnamiger timetree-Server existiert, entfernen Sie ihn zuerst und fügen Sie ihn wieder hinzu:

codex mcp remove timetree
codex mcp add timetree \
  --env TIMETREE_EMAIL=your-email@example.com \
  --env TIMETREE_PASSWORD_FILE=/absolute/path/to/timetree-password \
  -- python3 /absolute/path/to/timetree-mcp/src/timetree_mcp/server.py

Setzen Sie kein echtes Passwort in die Shell-History, in MCP-Toolargumente, die README oder den Quellcode.

Bei Verwendung des NPM wrappers ändern Sie den Server-Befehl wie folgt:

codex mcp add timetree \
  --env TIMETREE_EMAIL=your-email@example.com \
  --env TIMETREE_PASSWORD_FILE=/absolute/path/to/timetree-password \
  -- npx --yes timetree-mcp

MCP-Tools

Anmeldung und Abfragen

• timetree_login, timetree_logout, timetree_status

• timetree_keychain_status

• timetree_list_calendars, timetree_list_events, timetree_list_memos

• timetree_list_event_comments

• timetree_get_calendar_labels, timetree_get_calendar_members, timetree_get_calendar_virtual_members

Schreiboperationen

• timetree_create_event, timetree_update_event, timetree_delete_event

• timetree_create_memo, timetree_update_memo, timetree_delete_memo

• timetree_add_event_comment, timetree_update_event_comment, timetree_delete_event_comment

• timetree_update_calendar_labels

Zeiten können als ISO-8601-Zeichenkette oder Unix-Millisekunden übergeben werden; alle Schreibwerkzeuge verlangen ausdrücklich die Übergabe von confirm: true. Die Einladungs- und Entfernungs-Endpoints für Mitglieder wurden bis jetzt nicht verifiziert und sind deshalb absichtlich nicht enthalten.

Falls der TimeTree-Sync-Endpoint eines alten Kalenders -425 liefert, übersprungen wird dieser Kalender bei der Event-Abfrage und im Feld skipped_calendars gemeldet. Dabei schlagen nicht die gesamte Leseoperationen für alle anderen lesbaren Kalender fehl.

Hintergrundüberwachung

• timetree_start_monitor: startet das Hintergrund-Polling mit einem Intervall von 30–3600 Sekunden.

• timetree_monitor_status: Zeigt den Überwachungsstatus, das letzte Polling, Fehler und die Anzahl der Benachrichtigungen an.

• timetree_stop_monitor: stop the Überwachung.

Das erste Polling erzeugt nur eine Baseline; werden anschließend Änderungen erkannt, sendet der Server MCP notifications/message. Die Überwachung ist an den MCP-Prozess gekoppelt und endet, wenn der Client beendet wird.

Projektstruktur

src/timetree_mcp/          Python package 與 MCP server
bin/                       NPM wrapper launcher
scripts/                   本機設定輔助腳本
tests/                     standard-library unittest 測試
test/                      NPM wrapper 測試
.github/workflows/ci.yml   Continuous integration

Tests

python3 -m unittest discover -s tests -v
npm test

Der alte ego-browser transport bleibt in src/timetree_mcp/browser.py als Kompatibilitäts-Backup erhalten, wird aber standardmäßig nicht vom Server geladen.

Lizenz

Dieses Projekt steht unter der MIT License.