douyin-favorites-mcp · Servicio MCP de favoritos de Douyin

Servidor de Model Context Protocol (MCP) para favoritos de Douyin (抖音收藏夹 / 抖音收藏) — a través de una sesión de navegador con inicio de sesión, lee los favoritos de Douyin (favoritos predeterminados), carpetas de favoritos / álbumes (como «Aprendizaje») de tu propia cuenta, y exporta datos estructurados para que los usen asistentes de IA (Claude / WorkBuddy, etc.).

English: An MCP server that reads your personal Douyin (抖音) favorites and collection folders (收藏夹/专辑) via a logged-in browser session, for use with Claude / WorkBuddy and other MCP clients.

⚠️ Uso autorizado personal: esta herramienta solo lee los datos de favoritos de la cuenta actualmente conectada; no ofrece funciones de extracción de datos de terceros, evasión de captchas ni descifrado de firmas.

Funciones

Tipos de contenido compatibles: video + imagen y texto (artículos largos); se pueden extraer título / autor / datos de interacción / portada / duración.

Principio de funcionamiento

La interfaz web de Douyin tiene protección de firma en tiempo de ejecución, por lo que no se pueden falsificar llamadas API directamente. Este servicio utiliza:

1. Inicia un Chrome real con Playwright (perfil persistente);

2. Inicia sesión una vez escaneando el código QR; la cookie de sesión se guarda localmente;

3. Controla la interfaz de la página (hace clic en la pestaña «Favoritos» y luego en la subpestaña «Carpetas de favoritos»), intercepta las respuestas XHR;

4. Analiza y devuelve datos estructurados.

Interfaces verificadas (2026-08):

• Lista de carpetas de favoritos: GET /aweme/v1/web/collects/list/

• Contenido de carpetas de favoritos: GET /aweme/v1/web/collects/video/list/?collects_id=...&cursor=0&count=10

• Todos los favoritos: POST /aweme/v1/web/aweme/listcollection/ (el cursor está en el cuerpo del POST)

Instalación

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

pip install -e .
playwright install chromium

Configuración (WorkBuddy / Claude Desktop)

Añade en la configuración de MCP (por ejemplo, ~/.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 es la ubicación donde se guarda el perfil del navegador (estado de inicio de sesión); no lo incluyas en el control de versiones.

Primer uso

# 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>"})

El estado de inicio de sesión persiste entre sesiones; normalmente solo es necesario volver a escanear el código QR cada pocas semanas.

Pruebas

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

Notas y limitaciones conocidas

• La detección del estado de inicio de sesión se basa en la cookie de sesión (sessionid / sessionid_ss / sid_guard / sid_tt); no uses elementos del DOM para determinarlo (la página principal de Douyin muestra muchos avatares de autores incluso sin iniciar sesión, lo que provocaría falsos positivos).

• La página principal de Douyin nunca alcanza networkidle; toda la navegación usa domcontentloaded.

• La paginación de la página de favoritos se activa con la rueda del ratón real (primero mouse.move al área de contenido y luego wheel); window.scrollTo no funciona.

• La pestaña «Favoritos» debe activarse haciendo clic; el parámetro de URL ?showTab=favorite no funciona por sí solo.

• get_video_detail puede estar temporalmente no disponible debido a cambios en la interfaz de detalles de Douyin.

Descargo de responsabilidad

Este proyecto es solo para aprendizaje personal, investigación y organización de datos. Al usar esta herramienta, usted confirma que:

• Solo accede a los datos de cuentas de Douyin sobre las que tiene pleno acceso;

• No utilizará esta herramienta para extracción masiva, venta de datos, inflado de métricas u otras actividades ilegales o que infrinjan las normas;

• Entiende que las interfaces de Douyin pueden cambiar en cualquier momento, lo que puede hacer que la herramienta deje de funcionar temporalmente.

Cualquier consecuencia derivada del incumplimiento de los términos anteriores o de las leyes y regulaciones aplicables será responsabilidad exclusiva del usuario.

Licencia

MIT