douyin-favorites-mcp · MCP-Dienst für Douyin-Favoriten

MCP-Server für Douyin-Favoriten / Douyin-Sammlungen – Liest über eine angemeldete Browser-Sitzung die Favoriten (Standard-Favoriten), Favoritenordner / Alben (z. B. „Lernen") deines eigenen Kontos und exportiert strukturierte Daten für KI-Assistenten (Claude / WorkBuddy usw.).

Englisch: Ein MCP-Server, der über eine angemeldete Browser-Sitzung deine persönlichen Douyin (抖音) Favoriten und Sammlungsordner (收藏夹/专辑) liest, zur Verwendung mit Claude / WorkBuddy und anderen MCP-Clients.

⚠️ Persönliche Autorisierung: Dieses Tool liest nur die Favoritendaten des aktuell angemeldeten Kontos und bietet keine Funktionen zum Abrufen fremder Daten, Umgehen von Captchas oder Entschlüsseln von Signaturen.

Funktionen

Unterstützte Inhaltstypen: Videos + Bilder (lange Artikel), alle können Titel / Autor / Interaktionsdaten / Cover / Dauer extrahieren.

Funktionsweise

Die Douyin-Web-API verfügt über einen Laufzeit-Signaturschutz, sodass API-Aufrufe nicht direkt gefälscht werden können. Dieser Dienst verwendet:

1. Startet echtes Chrome mit Playwright (persistentes Profil);

2. Einmalige Anmeldung per QR-Code, Sitzungs-Cookie wird lokal gespeichert;

3. Steuert die Seiten-UI (klickt auf den Tab „Favoriten", dann auf den Untertab „Favoritenordner") und fängt XHR-Antworten ab;

4. Analysiert und gibt strukturierte Daten zurück.

Verifizierte Schnittstellen (2026-08):

• Favoritenordner-Liste: GET /aweme/v1/web/collects/list/

• Favoritenordner-Inhalt: GET /aweme/v1/web/collects/video/list/?collects_id=...&cursor=0&count=10

• Alle Favoriten: POST /aweme/v1/web/aweme/listcollection/ (cursor im POST-Body)

Installation

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .
playwright install chromium

Konfiguration (WorkBuddy / Claude Desktop)

Fügen Sie in der MCP-Konfiguration hinzu (z. B. ~/.workbuddy/mcp.json):

{
  "mcpServers": {
    "douyin-favorites": {
      "command": "C:/absolute/path/to/douyin-favorites/.venv/Scripts/python.exe",
      "args": ["-m", "douyin_favorites.server"],
      "env": {
        "DOUYIN_DATA_DIR": "C:/Users/<you>/.douyin-favorites"
      }
    }
  }
}

DOUYIN_DATA_DIR ist der Speicherort für das Browser-Profil (Anmeldestatus). Bitte nicht unter Versionskontrolle stellen.

Erste Verwendung

# 1. 登录（弹出 Chrome，扫码后自动关闭）
python scripts/verify.py

# 2. 或通过 MCP 调用：
#    douyin_login_start
#    douyin_login_status   -> {"logged_in": true}
#    list_collects         -> 列出收藏夹（id + 名称 + 数量）
#    get_collect_videos({"collects_id": "<id>"})

Der Anmeldestatus bleibt über Sitzungen hinweg erhalten; normalerweise ist nur alle paar Wochen eine erneute QR-Code-Anmeldung erforderlich.

Tests

pytest tests/ -v
python scripts/verify.py          # 端到端验证（需要登录态）
python scripts/verify_collects.py # 列收藏夹 + 第一个收藏夹的视频

Hinweise und bekannte Einschränkungen

• Die Erkennung des Anmeldestatus basiert auf dem Session-Cookie (sessionid / sessionid_ss / sid_guard / sid_tt), nicht auf DOM-Elementen (die Douyin-Startseite zeigt auch ohne Anmeldung viele Autoren-Avatare, was zu Fehlern führen würde).

• Die Douyin-Startseite erreicht nie networkidle; für alle Navigationen wird domcontentloaded verwendet.

• Die Paginierung der Favoritenseite wird durch echtes Mausrad ausgelöst (zuerst mouse.move in den Inhaltsbereich, dann wheel); window.scrollTo funktioniert nicht.

• Der Tab „Favoriten" muss angeklickt werden; der URL-Parameter ?showTab=favorite allein ist wirkungslos.

• get_video_detail kann aufgrund von Änderungen an der Detail-API von Douyin vorübergehend nicht verfügbar sein.

Haftungsausschluss

Dieses Projekt dient ausschließlich dem persönlichen Lernen, der Forschung und der Datenorganisation. Mit der Nutzung dieses Tools bestätigen Sie:

• Sie greifen nur auf Daten von Douyin-Konten zu, für die Sie über vollständige Zugriffsrechte verfügen;

• Sie werden dieses Tool nicht für Massen-Crawling, Datenhandel, Manipulation von Kennzahlen oder andere illegale/regelwidrige Aktivitäten verwenden;

• Sie verstehen, dass sich die Douyin-API jederzeit ändern kann, was zu vorübergehender Funktionsunfähigkeit des Tools führen kann.

Für jegliche Konsequenzen, die aus der Verletzung der oben genannten Bedingungen oder geltender Gesetze entstehen, ist der Nutzer selbst verantwortlich.

Lizenz

MIT