Donetick MCP Server

Ein Model Context Protocol (MCP) Server für die Donetick Aufgabenverwaltung. Ermöglicht Claude und anderen MCP-kompatiblen KI-Assistenten die Interaktion mit Ihrer Donetick-Instanz über eine ratenbegrenzte API.

Funktionen

• 16 MCP-Tools: Vollständige Aufgabenverwaltung (Auflisten, Abrufen, Erstellen, Erledigen, Aktualisieren, Löschen, Überspringen), Label-Organisation (Auflisten, Erstellen, Aktualisieren, Löschen), Kreis-Mitglieder-Informationen, Benutzerverwaltung (Kreisbenutzer auflisten, Benutzerprofil abrufen)

• Vollständige API-Integration: Verwendet die Donetick Full API (/api/v1/) mit allen Endpunkten, die korrekt mit abschließenden Schrägstrichen konfiguriert sind

• Vollständige Feldunterstützung: Alle 26+ Felder zur Aufgabenerstellung funktionieren, einschließlich Häufigkeitsmetadaten, rollierender Zeitpläne, mehrerer Zuweisungen, Zuweisungsstrategien, Benachrichtigungen, Labels, Priorität, Punkte, Unteraufgaben und mehr

• Einheitliche Feld-Schreibweise: camelCase-Felder durchgängig (name, description, dueDate, createdBy usw.)

• Spezialisierte Update-Tools: Aktualisieren von Aufgabendetails, Priorität und Zuweisung mit dedizierten Endpunkten

• JWT-Authentifizierung: Automatische Token-Verwaltung mit transparentem Refresh

• Intelligentes Caching: Intelligentes Caching für get_chore-Operationen (60s TTL standardmäßig)

• Ratenbegrenzung: Token-Bucket-Algorithmus verhindert API-Überlastung

• Wiederholungslogik: Exponentielles Backoff mit Jitter für widerstandsfähige Operationen

• Async/Await: Nicht blockierende Operationen mit httpx

• Eingabevalidierung: Pydantic-Feldvalidatoren mit Bereinigung

• Sicherheitsgehärtet: HTTPS-Erzwingung, bereinigtes Logging, sichere Fehlermeldungen, JWT-Token-Sicherheit

• Docker-Unterstützung: Containerisierter Einsatz mit Sicherheitsbest Practices

• Umfassende Tests: Mocking für Unit-/Integrationstests + Live-API-Test-Framework mit pytest

• Typsicherheit: Pydantic-Modelle für Anfrage-/Antwortvalidierung

Schnellstart

Einfachste Installation (Claude Code CLI):

claude mcp add donetick uvx donetick-mcp-server@latest

Konfigurieren Sie dann Ihre Donetick-Anmeldedaten, wenn Sie dazu aufgefordert werden.

Oder manuell mit uvx installieren:

# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to Claude Desktop config
# ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Vorteile:

• ✅ Keine Installation erforderlich – läuft direkt von PyPI

• ✅ Automatische Updates mit dem Flag --refresh

• ✅ Isolierte Umgebung – keine Konflikte

• ✅ Funktioniert auf Windows, macOS, Linux

Voraussetzungen

• Donetick-Instanz (selbst gehostet oder in der Cloud)

• Donetick-Kontoanmeldedaten (Benutzername und Passwort)

• Für die uvx-Methode: uv installiert (siehe Schnellstart)

• Für andere Methoden: Python 3.11 oder höher

Installation

Option 1: uvx (Empfohlen – Keine Installation erforderlich)

Siehe Schnellstart oben.

Das Flag --refresh stellt sicher, dass Sie immer die neueste Version erhalten, wenn Claude Desktop neu startet.

Option 2: Docker

1. Repository klonen:

   git clone https://github.com/jason1365/donetick-mcp-server.git
   cd donetick-mcp-server

2. .env-Datei erstellen:

   cp .env.example .env
   # Edit .env with your configuration

3. Umgebungsvariablen konfigurieren:

   DONETICK_BASE_URL=https://your-instance.com
   DONETICK_USERNAME=your_username
   DONETICK_PASSWORD=your_password
   LOG_LEVEL=INFO

4. Erstellen und ausführen:

   docker-compose build
   docker-compose up -d

Option 3: pip install (Für Systemintegration)

Wenn Sie global oder in einer virtuellen Umgebung installieren möchten:

# Install from PyPI
pip install donetick-mcp-server

# Or install for development
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
pip install -e .

# Run the server
donetick-mcp-server
# Or: python -m donetick_mcp.server

Konfigurieren Sie dann Claude Desktop, um den installierten Befehl zu verwenden:

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Authentifizierung

Der MCP-Server verwendet eine JWT-basierte Authentifizierung mit Ihren Donetick-Anmeldedaten.

Was Sie benötigen:

• Ihren Donetick-Benutzernamen (wie beim Web-Login)

• Ihr Donetick-Passwort (wie beim Web-Login)

Wie es funktioniert:

1. Der Server meldet sich beim Start mit Ihren Anmeldedaten an

2. JWT-Token wird empfangen und im Speicher abgelegt

3. Token wird automatisch vor Ablauf aktualisiert

4. Keine manuelle Token-Verwaltung erforderlich

Sicherheit:

• Anmeldedaten werden nur in Umgebungsvariablen oder der .env-Datei gespeichert

• JWT-Tokens nur im Speicher (niemals auf die Festplatte geschrieben)

• Automatische Token-Aktualisierung verhindert Sitzungsablauf

• HTTPS für alle Verbindungen erforderlich

Claude Desktop Integration

Einfachste Methode – Claude Code CLI:

claude mcp add donetick uvx donetick-mcp-server@latest

Oder die Konfigurationsdatei manuell bearbeiten:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

uvx-Konfiguration (Empfohlen)

{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Hinweis: Das Flag --refresh aktualisiert automatisch auf die neueste Version.

Docker-Konfiguration

{
  "mcpServers": {
    "donetick": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "donetick-mcp-server",
        "python",
        "-m",
        "donetick_mcp.server"
      ]
    }
  }
}

pip install Konfiguration

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Nachdem Sie die Konfiguration aktualisiert haben, starten Sie Claude Desktop neu.

Verfügbare Tools

1. list_chores

Alle Aufgaben mit optionaler Filterung auflisten.

Parameter:

• filter_active (boolean, optional): Nach aktivem Status filtern

• assigned_to_user_id (integer, optional): Nach zugewiesener Benutzer-ID filtern

Beispiel:

List all active chores assigned to me

2. get_chore

Details einer bestimmten Aufgabe nach ID abrufen.

Parameter:

• chore_id (integer, erforderlich): Die Aufgaben-ID

Beispiel:

Show me details of chore 123

3. create_chore

Eine neue Aufgabe mit vollständiger Konfigurationsunterstützung erstellen.

Basis-Parameter:

• name (string, erforderlich): Aufgabenname (1-200 Zeichen)

• description (string, optional): Aufgabenbeschreibung (max. 5000 Zeichen)

• due_date (string, optional): Fälligkeitsdatum im Format YYYY-MM-DD oder RFC3339

• created_by (integer, optional): Benutzer-ID des Erstellers

Wiederholungs-/Häufigkeitsparameter:

• frequency_type (string, optional): Wie oft sich die Aufgabe wiederholt – „once", „daily", „weekly", „monthly", „yearly", „interval_based" (Standard: „once")

• frequency (integer, optional): Häufigkeitsmultiplikator, z. B. 1=wöchentlich, 2=zweiwöchentlich (Standard: 1)

• frequency_metadata (object, optional): Zusätzliche Häufigkeitskonfiguration wie {"days": [1,3,5], "time": "09:00"}

• is_rolling (boolean, optional): Rollierender Zeitplan (nächster Termin basierend auf Erledigung) vs. fest (Standard: false)

Benutzerzuweisungs-Parameter:

• assigned_to (integer, optional): Primäre zugewiesene Benutzer-ID

• assignees (array, optional): Mehrere Zuweisungen als [{"userId": 1}, {"userId": 2}]

• assign_strategy (string, optional): Zuweisungsstrategie – „least_completed", „round_robin", „random" (Standard: „least_completed")

Benachrichtigungsparameter:

• notification (boolean, optional): Benachrichtigungen aktivieren (Standard: false)

• nagging (boolean, optional): Erinnerungsbenachrichtigungen aktivieren (Standard: false)

• predue (boolean, optional): Benachrichtigungen vor Fälligkeit aktivieren (Standard: false)

Organisationsparameter:

• priority (integer, optional): Prioritätsstufe 1-5 (1=niedrigste, 5=höchste)

• labels (array, optional): Label-Tags wie ["cleaning", "outdoor"]

Statusparameter:

• is_active (boolean, optional): Aktiver Status – inaktive Aufgaben werden ausgeblendet (Standard: true)

• is_private (boolean, optional): Private Aufgabe, nur für den Ersteller sichtbar (Standard: false)

Gamification-Parameter:

• points (integer, optional): Punkte, die für die Erledigung vergeben werden

Erweiterte Parameter:

• sub_tasks (array, optional): Unteraufgaben/Checkliste

Beispiele:

Create a simple one-time chore:
Create a chore called "Take out trash" due on 2025-11-10

Create a recurring chore with notifications:
Create a weekly chore "Clean kitchen" every Monday at 9am with priority 4,
enable nagging notifications, and assign it to user 1

Create an advanced chore:
Create a chore "Grocery shopping" that repeats weekly on Mondays and Wednesdays,
assign to users 1 and 2 using round robin strategy, with priority 3,
labels "shopping" and "outdoor", and award 10 points

4. complete_chore

Eine Aufgabe als erledigt markieren.

Parameter:

• chore_id (integer, erforderlich): Die Aufgaben-ID

• completed_by (integer, optional): Benutzer-ID, die die Aufgabe erledigt hat

Beispiel:

Mark chore 123 as complete

5. delete_chore

Eine Aufgabe endgültig löschen. Nur der Ersteller kann löschen.

Parameter:

• chore_id (integer, erforderlich): Die Aufgaben-ID

Beispiel:

Delete chore 123

6. get_circle_members

Alle Mitglieder in Ihrem Kreis (Haushalt/Team) abrufen. Zeigt, wem Sie Aufgaben zuweisen können.

Parameter: Keine

Rückgabe:

• Benutzer-ID

• Benutzername

• Anzeigename

• Rolle (admin/member)

• Aktiver Status

• Punkte und eingelöste Punkte

Beispiel:

Show me who's in my household
Who can I assign chores to?
List all circle members

Konfiguration

Umgebungsvariablen

Ratenbegrenzung

Der Server implementiert einen Token-Bucket-Ratenbegrenzer, um API-Überlastung zu verhindern:

• Standard: 10 Anfragen pro Sekunde mit einer Burst-Kapazität von 10

• Konservativ: Startet konservativ und kann basierend auf Ihrer Donetick-Instanz erhöht werden

• Respektiert 429: Reduziert automatisch die Rate, wenn die API eine Ratenbegrenzung meldet

Wiederholungslogik

• Exponentielles Backoff mit Jitter für vorübergehende Fehler

• Maximal 3 Wiederholungen für die meisten Operationen

• Intelligente Wiederholung: Nur bei 5xx-Fehlern und 429 (Ratenbegrenzung) wiederholen

• Keine Wiederholung bei 4xx: Client-Fehler schlagen sofort fehl (außer 429)

Entwicklung

Tests ausführen

Mock-Tests (schnell, keine Donetick-Instanz erforderlich):

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (unit + integration with mocks)
pytest

# Run with coverage
pytest --cov=donetick_mcp --cov-report=html

# Run specific test file
pytest tests/test_client.py
pytest tests/test_server.py

# Run with verbose output
pytest -v

Live-API-Tests (erfordert Donetick-Instanz):

# Create .env file with credentials (see Configuration section)
# Then run live API integration tests
pytest tests/integration/test_live_api.py -v

# Skip live tests
pytest -m "not live_api"

# Run only live tests
pytest -m live_api

Details zur Testabdeckung:

• Mock-Tests validieren Logik, Wiederholungsverhalten, Ratenbegrenzung, Fehlerbehandlung

• Live-API-Tests überprüfen Endpunkt-Routing, Feld-Schreibweisen-Kompatibilität, Antwortformate

• Vollständige Abdeckung stellt sowohl die Zuverlässigkeit des API-Clients als auch die Korrektheit der MCP-Tools sicher

Projektstruktur

donetick-mcp-server/
├── src/donetick_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── client.py           # Donetick API client
│   ├── models.py           # Pydantic data models
│   └── config.py           # Configuration management
├── tests/
│   ├── test_client.py      # API client tests
│   └── test_server.py      # MCP server tests
├── tmp/                    # Temporary files (gitignored)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md

Hinweis: Das Verzeichnis tmp/ wird für temporäre Testskripte und Analyse-Dateien während der Entwicklung verwendet. Es ist in .gitignore und nicht in Releases enthalten.

API-Dokumentation

Dieser Server verwendet die Donetick Full API (/api/v1/) mit JWT-Authentifizierung.

Offizielle Ressourcen

• Donetick-Dokumentation: https://docs.donetick.com/

• Donetick GitHub: https://github.com/donetick/donetick

API-Architektur

Verwendete Endpunkte:

• Aufgaben auflisten: GET /api/v1/chores/ (erfordert abschließenden Schrägstrich)

• Aufgabe abrufen: GET /api/v1/chores/{id} (enthält Unteraufgaben)

• Aufgabe erstellen: POST /api/v1/chores/

• Aufgabe aktualisieren: PUT /api/v1/chores/{id} (Name, Beschreibung, nextDueDate)

• Priorität aktualisieren: PUT /api/v1/chores/{id}/priority

• Zuweisung aktualisieren: PUT /api/v1/chores/{id}/assignee

• Aufgabe überspringen: PUT /api/v1/chores/{id}/skip

• Aufgabe erledigen: POST /api/v1/chores/{id}/do

• Aufgabe löschen: DELETE /api/v1/chores/{id}

• Mitglieder abrufen: GET /api/v1/circles/members/ (erfordert abschließenden Schrägstrich)

Wichtig: Listen-Endpunkte erfordern abschließende Schrägstriche (/api/v1/chores/, /api/v1/circles/members/). Dies wird automatisch vom Client behandelt.

Wichtige Hinweise

1. Full API verwendet: Nicht die externe API (eAPI) – verwendet die interne Full API

2. Feld-Schreibweise: Einheitliches camelCase durchgängig (name, description, dueDate, createdBy)

3. Abschließende Schrägstriche: Listen-Endpunkte enthalten abschließende Schrägstriche für korrektes Routing

4. Authentifizierung: JWT-Bearer-Tokens mit automatischer Verwaltung

5. Vollständige Funktionsunterstützung: Alle 26+ Felder zur Aufgabenerstellung verfügbar

6. Automatische Token-Aktualisierung: JWT-Tokens werden transparent aktualisiert

7. Kreisbezogen: Alle Operationen sind auf Ihren Kreis (Haushalt/Team) beschränkt

8. Keine Premium-Einschränkungen: Alle Funktionen über die Full API verfügbar

Fehlerbehebung

Häufige Probleme

„DONETICK_BASE_URL environment variable is required"

• Stellen Sie sicher, dass Ihre .env-Datei existiert und korrekt formatiert ist

• Für Docker: Stellen Sie sicher, dass die Umgebungsvariablen in docker-compose.yml übergeben werden

„Rate limited, waiting..."

• Der Server respektiert die API-Ratenbegrenzung

• Erwägen Sie, RATE_LIMIT_PER_SECOND zu reduzieren, wenn dies häufig vorkommt

„Connection refused" oder Zeitüberschreitungen

• Überprüfen Sie, ob die URL Ihrer Donetick-Instanz korrekt ist

• Prüfen Sie, ob Ihre Donetick-Instanz erreichbar ist

• Stellen Sie sicher, dass Firewall-Regeln ausgehende Verbindungen zulassen

"401 Nicht autorisiert" oder "Ungültige Anmeldedaten"

• Überprüfen Sie, ob Ihr Benutzername und Ihr Passwort korrekt sind

• Stellen Sie sicher, dass Ihr Konto nicht gesperrt oder deaktiviert ist

• Vergewissern Sie sich, dass Sie sich mit denselben Anmeldedaten in der Donetick-Weboberfläche anmelden können

• Überprüfen Sie die Umgebungsvariablen auf Tippfehler

Tools werden in Claude nicht angezeigt

• Starten Sie Claude Desktop nach Konfigurationsänderungen neu

• Überprüfen Sie die Claude Desktop-Protokolle auf Fehler

• Vergewissern Sie sich, dass der Pfad zur Konfigurationsdatei korrekt ist

Debugging

Debug-Ausgabe aktivieren:

export LOG_LEVEL=DEBUG

Oder in Docker:

environment:
  - LOG_LEVEL=DEBUG

Docker-Logs anzeigen:

docker-compose logs -f donetick-mcp

Sicherheit

• Anmeldedaten: Übergeben Sie Anmeldedaten niemals an die Versionsverwaltung (verwenden Sie eine .env-Datei)

• JWT-Tokens: Nur im Arbeitsspeicher gespeichert, nie auf die Festplatte geschrieben

• Automatische Token-Aktualisierung: Verhindert Sitzungsablauf ohne Benutzereingriff

• Docker-Isolation: Läuft als Nicht-Root-Benutzer im Container

• Ressourcenbeschränkungen: Speicher- und CPU-Grenzen verhindern Ressourcenerschöpfung

• Eingabevalidierung: Pydantic-Modelle validieren alle Eingaben

• HTTPS erforderlich: Server erzwingt HTTPS für alle Donetick-Verbindungen

Mitwirken

Beiträge sind willkommen! Bitte:

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch

3. Fügen Sie Tests für neue Funktionalitäten hinzu

4. Stellen Sie sicher, dass alle Tests bestehen

5. Reichen Sie einen Pull-Request ein

Lizenz

MIT-Lizenz – siehe LICENSE-Datei für Details

Danksagungen

• Donetick – Open-Source-Aufgabenverwaltung

• Model Context Protocol – MCP-Spezifikation

• Anthropic – MCP SDK und Claude

Support

• Issues: https://github.com/jason1365/donetick-mcp-server/issues

• Donetick-Dokumentation: https://docs.donetick.com

• MCP-Dokumentation: https://modelcontextprotocol.io

Erstellt mit ❤️ für die Donetick- und MCP-Communities