ticktick-mcp

MCP-Server für die TickTick-Aufgabenverwaltung. Erstellen, aktualisieren, abschließen, verschieben und filtern Sie Aufgaben über die TickTick-v2-API, mit felderhaltenden Updates, Wochentags-Datumsvalidierung, Read-after-Write-Verifizierung und idempotenter Abschlussverfolgung.

Entwickelt für Claude Code und andere MCP-Clients.

Inoffiziell. Nicht mit TickTick Ltd. verbunden. Basierend auf ticktick-py (MIT).

Funktionen

• Vollständiger Aufgabenlebenszyklus – erstellen, aktualisieren, abschließen, verschieben, als Unteraufgabe einfügen und löschen

• Felderhaltende Updates – ticktick_update_task ruft die Aufgabe erneut ab und überlagert nur die von Ihnen gesetzten Felder, sodass die API die weggelassenen nie überschreibt

• Wochentagsvalidierung – jeder Aufruf, der ein Datum setzt, muss den Wochentag bestätigen, um Datumsfehler (off-by-one) zu erkennen, bevor sie den Server erreichen

• Read-after-Write-Verifizierung – create/update liest die Aufgabe erneut und zeigt _verification_warnings an, wenn das Server-Echo nicht übereinstimmt

• Kompakte Auflistung – Listen-Tools geben standardmäßig eine reduzierte Ansicht zurück, sodass große Projekte unter dem MCP-Ergebnisgrößenlimit bleiben (siehe unten)

• Frische Lesevorgänge – Lese-Tools synchronisieren den Serverstatus bei Bedarf neu, sodass Änderungen, die in der TickTick-App auf anderen Geräten vorgenommen wurden, ohne Neustart sichtbar werden

• Abschlussverfolgung – markieren Sie abgeschlossene Aufgaben als verarbeitet, damit ein Agent jede genau einmal überprüft

Related MCP server: ticktick-mcp-server

Voraussetzungen

• Python 3.13+

• uv (empfohlen – siehe Installationshinweis unten)

• Ein TickTick-Konto

• Eine registrierte TickTick-App für OAuth-Anmeldedaten (kostenlos – developer.ticktick.com)

Installation

git clone https://github.com/partymola/ticktick-mcp
cd ticktick-mcp
uv sync

Dies erstellt ein .venv und installiert aus uv.lock, sodass Sie das Konsolenskript unter .venv/bin/ticktick-mcp bzw. unter Windows unter .venv\Scripts\ticktick-mcp erhalten. Jeder unten genannte Befehl verwendet die POSIX-Schreibweise.

pip install . funktioniert ebenfalls. Der Fork von ticktick-py, den dieser Server benötigt, ist als direkter Git-Verweis in dependencies festgelegt, was sowohl pip als auch uv berücksichtigen; uv sync wird empfohlen, da es die exakten Versionen aus uv.lock installiert, anstatt sie neu aufzulösen.

Anmeldedaten

Für die TickTick-Anmeldung werden zwei Dinge benötigt: eine OAuth-App (Client-ID + Secret) und Ihre eigene Kontoanmeldung.

1. Registrieren Sie eine App unter developer.ticktick.com. Setzen Sie die Redirect-URI auf http://localhost:8080/redirect. Notieren Sie sich die Client-ID und das Client-Secret.

2. Kopieren Sie die Vorlage in das Verzeichnis, das der Server liest, und füllen Sie sie aus:

   mkdir -p ~/.config/ticktick-mcp && cp .env.example ~/.config/ticktick-mcp/.env

   TICKTICK_CLIENT_ID=your_client_id
   TICKTICK_CLIENT_SECRET=your_client_secret
   TICKTICK_REDIRECT_URI=http://localhost:8080/redirect
   TICKTICK_USERNAME=your_ticktick_email
   TICKTICK_PASSWORD=your_ticktick_password

3. Diese Datei enthält Ihr Kontopasswort im Klartext, und der Server erstellt sie nicht. Sichern Sie sie daher selbst. Unter POSIX:

   chmod 700 ~/.config/ticktick-mcp
   chmod 600 ~/.config/ticktick-mcp/.env

   Das sind POSIX-Modusbits, die unter Windows keine Wirkung haben: Der Zugriff folgt dort den ACLs, die die Datei von ihrem übergeordneten Verzeichnis erbt. Für Windows wird hier kein Äquivalent der beiden Befehle dokumentiert.

   Die beiden Token-Dateien daneben werden nur für den Besitzer erstellt, ebenso wie ein Konfigurationsverzeichnis, das der Server erstellt – aber ein bereits vorhandenes wird so belassen, wie es ist. Auch das sind POSIX-Modi, die auch unter Windows gesetzt werden, wo sie jedoch nicht einschränken, wer was lesen darf.

Autorisieren Sie einmal in einem Terminal, bevor Sie den Server registrieren:

.venv/bin/ticktick-mcp auth

Es öffnet einen Browser und fordert Sie auf, die URL, auf der Sie landen, zurückzupasten, und beendet sich dann. Das Token wird neben Ihrer .env als .token-oauth zwischengespeichert und bei jedem späteren Start wiederverwendet. TickTick stellt kein Refresh-Token aus, daher wiederholt sich dies, wenn das Token abläuft – führen Sie denselben Befehl erneut aus.

Lassen Sie diesen Schritt nicht innerhalb des MCP-Servers ablaufen. Die Eingabeaufforderung liest von der Standardeingabe, die für einen Stdio-Server der JSON-RPC-Kanal ist. Ein nicht autorisierter erster Tool-Aufruf öffnet daher einen Browser auf dem Host und blockiert. In einem Container kann er überhaupt nicht abgeschlossen werden – führen Sie auth auf dem Host aus und mounten Sie das Konfigurationsverzeichnis.

Der Benutzername/Passwort-Teil benötigt keinen separaten Schritt: Der Server meldet sich beim ersten Tool-Aufruf verzögert an und speichert dieses Sitzungstoken als .token-v2, sodass er Ihre Anmeldedaten nicht bei jedem Start erneut übermittelt.

Der Server sucht nach .env in dieser Reihenfolge: das Argument --dotenv-dir <path>, dann die Umgebungsvariable TICKTICK_MCP_DOTENV_DIR, dann ~/.config/ticktick-mcp/. Wenn keine .env gefunden wird, greift er direkt auf die TICKTICK_*-Umgebungsvariablen zurück, was für Container-/CI-Nutzung praktisch ist.

Datenschutz und die inoffizielle API

Ihre TickTick-Anmeldedaten befinden sich nur in Ihrer lokalen .env (oder in der Umgebung) und werden nur an TickTicks eigene Server gesendet – niemals an den Entwickler oder Dritte. Der Server liest und schreibt nur Ihr eigenes Konto.

Dieser Server verwendet TickTicks inoffizielle v2-API (über ticktick-py) anstelle der offiziellen Open API. Das ist eine bewusste Entscheidung: Die offizielle API hat keinen Endpunkt für abgeschlossene Aufgaben, keine Tags und keine projektübergreifende Aufgabenauflistung – alles, worauf dieser Server angewiesen ist. Siehe docs/why-not-the-official-api.md für die vollständige Begründung, den Risikoabwägung und die Auslöser, die uns zum Umdenken bewegen würden.

Bei Claude Code registrieren

claude mcp add -s user ticktick -- /path/to/ticktick-mcp/.venv/bin/ticktick-mcp --dotenv-dir /path/to/config

--dotenv-dir ist optional, wenn Ihre .env in ~/.config/ticktick-mcp/ liegt oder Sie die TICKTICK_*-Variablen über die Umgebung bereitstellen.

Fragen Sie Claude dann zum Beispiel:

• „Was steht diese Woche auf meiner TickTick-Liste?“

• „Füge eine Aufgabe hinzu, um Freitag um 9 Uhr den Zahnarzt anzurufen.“

• „Markiere die Einkaufsaufgabe als erledigt.“

• „Verschiebe die Budgetaufgabe in das Projekt Finance.“

Docker

Images werden unter ghcr.io/partymola/ticktick-mcp veröffentlicht. Tags tragen ein v-Präfix (:vX.Y.Z), und :latest folgt der neuesten Version.

Autorisieren Sie zuerst auf einem Rechner mit Browser und mounten Sie dann dieses Verzeichnis. Das ist der einzige Weg, und er gilt auch bei docker run -it: Die zugrunde liegende Bibliothek öffnet den Browser selbst und druckt die URL nie aus, sodass es nichts gibt, das aus einem Container ohne Browser kopiert werden könnte. Sie wartet dann auf diese URL auf der Standardeingabe, die für einen Stdio-Server der JSON-RPC-Kanal ist – ein Container, der gegen ein Verzeichnis ohne zwischengespeichertes Token gestartet wird, schlägt also auch nicht sauber fehl, sondern verbraucht die Anfragen Ihres Clients, während er auf Eingaben wartet, die nie eintreffen.

Für die Autorisierung ist eine Quellinstallation (Installation) und die Anmeldedaten aus Anmeldedaten erforderlich – es gibt kein veröffentlichtes Paket, um sie auszuführen. Führen Sie nicht pip install ticktick-mcp aus: Dieser Name auf PyPI gehört zu einem nicht verwandten Projekt mit einer fast identischen Beschreibung.

.venv/bin/ticktick-mcp auth       # once, on the host, in a terminal

claude mcp add -s user ticktick -- \
  docker run --rm -i --user $(id -u):$(id -g) \
  -v ~/.config/ticktick-mcp:/data \
  ghcr.io/partymola/ticktick-mcp:latest

-i ist erforderlich – der Server spricht JSON-RPC über stdin und stdout.

--user ist vorhanden, weil der Container standardmäßig als root läuft und alles, was er in das gemountete Verzeichnis schreibt, root gehört – danach kann das hostseitige ticktick-mcp seinen Sitzungstoken-Cache nicht mehr aktualisieren und fällt bei jedem Start auf eine gedrosselte Anmeldung zurück. Sie werden es wieder auf dem Host ausführen: Das OAuth-Token hat kein Refresh, daher wiederholt sich auth beim Ablauf.

Mounten Sie ein Verzeichnis, das bereits autorisiert ist, niemals ein leeres Volume. /data enthält die .env, das zwischengespeicherte OAuth-Token, das v2-Sitzungstoken und die Datenbank für die Abschlussverfolgung. Ein frisches Volume hat keines davon, und der Passwort-Anmelde-Fallback wird in eine 15-30-minütige Sperre gedrosselt.

Wenn Sie keine .env auf der Festplatte behalten möchten, übergeben Sie die Anmeldedaten stattdessen als Umgebungsvariablen. Der Mount ist weiterhin erforderlich – er enthält den Token-Cache, nicht nur die .env:

docker run --rm -i --user $(id -u):$(id -g) \
  -v ~/.config/ticktick-mcp:/data \
  -e TICKTICK_CLIENT_ID -e TICKTICK_CLIENT_SECRET \
  -e TICKTICK_USERNAME -e TICKTICK_PASSWORD \
  ghcr.io/partymola/ticktick-mcp:latest

Wenn Sie jede Variable ohne Wert benennen, wird sie von Ihrer Shell durchgereicht, sodass kein Geheimnis im Befehl oder in der Shell-Historie erscheint. Diese überschreiben eine gemountete .env: Die Datei wird ohne override geladen, sodass alles, was bereits in der Umgebung vorhanden ist, gewinnt. Für die Autorisierung müssen diese Variablen weiterhin auf dem Host exportiert sein, da auth ebenfalls keine .env lesen kann.

CLI

ticktick-mcp                       Start the MCP server (stdio transport)
ticktick-mcp --dotenv-dir PATH     Directory holding the .env file
ticktick-mcp --version             Print the installed package version

auth ist der einzige weitere Unterbefehl, und er existiert, damit der Browser-Schritt in einem Terminal statt im Server stattfindet. Alle Aufgabenoperationen erfolgen über die unten aufgeführten MCP-Tools.

MCP-Tools

Projekte: Name oder ID

Jedes Tool, das eine Projekt-ID akzeptiert, akzeptiert auch den Namen des Projekts – ticktick_create_task, ticktick_get_tasks_from_project, ticktick_update_task, ticktick_move_task, ticktick_delete_tasks, ticktick_filter_tasks sowie beide Tools zur Abschlussverfolgung:

ticktick_create_task(title="Renew insurance", project_id="Home Admin")

Namen werden ohne Beachtung der Groß-/Kleinschreibung abgeglichen, wobei umgebende Leerzeichen ignoriert werden, und "Inbox" wird zu Ihrem Posteingang aufgelöst. IDs funktionieren weiterhin unverändert und haben immer Vorrang, sodass sich nichts ändert, was heute funktioniert.

Der einzige neue Fehler ist Mehrdeutigkeit: Wenn zwei Projekte denselben Namen haben, schlägt der Aufruf fehl und nennt beide IDs, anstatt eines auszuwählen, da eine Vermutung die Aufgabe an einem Ort ablegen würde, an dem Sie nicht suchen würden. Alles andere, das der Server nicht auflösen kann, wird unverändert an die API übergeben, genau wie zuvor.

Die beiden Abschlussverfolgungs-Tools sind die Ausnahme: Sie lehnen eine Projektreferenz ab, die sie nicht bestätigen können, anstatt sie weiterzugeben, weil dieser Wert der Schlüssel ist, unter dem ihre lokale Datenbank geschrieben wird. Eine nicht auflösbare Referenz würde eine Zeile schreiben, die eine spätere Suche per ID nicht finden kann. Wenn die Projektliste nicht aktualisiert werden konnte, um sie zu prüfen, geben sie das an (outcome: "project_list_unverifiable") anstatt zu behaupten, das Projekt existiere nicht.

Aufgaben auflisten: standardmäßig kompakt

Die listen-zurückgebenden Tools – ticktick_get_tasks_from_project und ticktick_filter_tasks – verwenden standardmäßig detail="compact". Die kompakte Ausgabe behält die für das Durchsuchen relevanten Felder (id, projectId, title, dueDate, startDate, priority, status, isAllDay, timeZone, tags) sowie eine contentPreview (die ersten ~200 Zeichen von content) und verwirft die schweren content/desc/Checklisten-items-Blobs und sperrige Sync-Metadaten. Dadurch bleiben große Projekte unter dem MCP-Ergebnisgrößenlimit, sodass der Client das Ergebnis nicht auf die Festplatte auslagern muss. Die Stichwortsuche funktioniert weiterhin gegen title und contentPreview.

• Brauchst du die vollständigen Objekte? Übergib detail="full".

• Brauchst du den vollständigen Inhalt einer Aufgabe? Verwende ticktick_get_by_id.

• Bearbeiten einer Aufgabe: Rufe zuerst das vollständige Objekt mit ticktick_get_by_id ab und sende dann jedes Feld über ticktick_update_task zurück. Die TickTick-API löscht jedes Feld, das in einem Update weggelassen wird, daher darf eine kompakte Ausgabe niemals ein Update speisen.

Wenn ein kompaktes Ergebnis das Größenbudget immer noch überschreiten würde, werden die am frühesten fälligen Aufgaben zurückgegeben und ein abschließendes _truncation_note-Element berichtet, wie viele weggelassen wurden – nichts wird stillschweigend verworfen. Erreiche den Rest mit einer engeren ticktick_filter_tasks-Abfrage, detail="full" oder ticktick_get_by_id.

Aktualität: Lesezugriffe bleiben aktuell

Das TickTick-Konto kann von der App auf anderen Geräten bearbeitet werden, während der Server läuft. Um zu verhindern, dass Lesezugriffe veralten, synchronisieren die Lesetools den Serverstatus bei Bedarf neu, gedrosselt auf höchstens einmal pro Fenster (Standard 15s, überschreibbar mit TICKTICK_MCP_SYNC_TTL_SECONDS). Eine Änderung, die anderswo vorgenommen wird, wird innerhalb dieses Fensters sichtbar; rufe ticktick_sync auf, um eine sofortige Aktualisierung zu erzwingen und die aktuellen Aufgaben-/Projektzahlen zu erhalten. Schlägt eine Synchronisierung fehl, wird der zuletzt bekannte Zustand ausgeliefert, anstatt einen Fehler zu melden – außer bei ticktick_get_all, das bei jedem Aufruf aktualisiert und den Fehler stattdessen meldet, da ein vollständiger Dump der falsche Ort ist, um eine veraltete Antwort stillschweigend zu liefern.

Konfiguration

Schützen von Aufgaben vor Änderungen

Einige Aufgaben sollten niemals von einem Agenten geändert werden, egal was ihm aufgetragen wird. Liste ihre IDs in TICKTICK_MCP_PROTECTED_TASK_IDS:

TICKTICK_MCP_PROTECTED_TASK_IDS="60ca9dbc8f08516d9dd56324,60ca9dbc8f08516d9dd56325"

ticktick_update_task, ticktick_complete_task, ticktick_delete_tasks, ticktick_move_task und ticktick_make_subtask lehnen dann jeden Aufruf ab, der eine geschützte Aufgabe benennt, und geben outcome: "protected_task" zurück. Es wird keine Anfrage gesendet, die die Aufgabe liest oder schreibt. Ein Batch-Löschen, das eine geschützte ID enthält, wird vollständig abgelehnt und nicht teilweise angewendet, da ein teilweises Löschen nicht rückgängig gemacht werden kann.

Da TickTick Löschen und Verschieben über Unteraufgaben propagiert, lehnen delete, move und make_subtask auch ab, wenn eine geschützte Aufgabe das übergeordnete Element oder die Unteraufgabe einer von dir benannten Aufgabe ist. Diese Prüfung aktualisiert zuerst den lokalen Zustand, sodass sie eine Anfrage pro Löschen, Verschieben oder Neu-Zuordnen hinzufügt, während Schutz konfiguriert ist – und gibt outcome: "protection_unverifiable" zurück, wenn diese Aktualisierung fehlschlägt, da sie eine geschützte Unteraufgabe auf einem Snapshot, den sie nicht aktualisieren konnte, nicht ausschließen kann. Wenn die Variable nicht gesetzt ist, wird keine zusätzliche Arbeit geleistet. IDs werden unter Ignorieren von umgebenden Leerzeichen, Anführungszeichen und Groß-/Kleinschreibung abgeglichen. Das Lesen geschützter Aufgaben funktioniert immer.

Anmeldedaten (TICKTICK_CLIENT_ID, TICKTICK_CLIENT_SECRET, TICKTICK_REDIRECT_URI, TICKTICK_USERNAME, TICKTICK_PASSWORD) werden aus der .env-Datei oder, falls nicht vorhanden, direkt aus der Umgebung gelesen.

Datensicherheit

Ein Pre-Commit-Hook (scripts/check-no-data.sh) blockiert versehentliches Committen von Datenbanken, Anmeldedaten und großen Dateien – *.db und Backup-Varianten, alles unter config/ außer .gitkeep und *.example*, sowie Dateien über 100KB (außer uv.lock). Installiere ihn nach dem Klonen:

ln -sf ../../scripts/check-no-data.sh .git/hooks/pre-commit

Mitwirken

Siehe CONTRIBUTING.md für das Entwicklungssetup, den Testworkflow und den Pre-Commit-Hook. Änderungen werden in CHANGELOG.md verfolgt.

Lizenz

GPL-3.0-or-later