douyin-favorites-mcp · MCP-сервис для избранного 抖音

MCP-сервер для избранного 抖音 / закладок 抖音 — через браузерную сессию с авторизацией читает избранное вашего собственного аккаунта (избранное по умолчанию), папки избранного / альбомы (например, «Учёба») и экспортирует структурированные данные для ИИ-ассистентов (Claude / WorkBuddy и др.).

Английский: MCP-сервер, который читает личные избранное и папки избранного (收藏夹/专辑) Douyin (抖音) через браузерную сессию с авторизацией, для использования с Claude / WorkBuddy и другими MCP-клиентами.

⚠️ Использование только с личного разрешения: этот инструмент читает только данные избранного текущего авторизованного аккаунта и не предоставляет функций сбора чужих данных, обхода CAPTCHA или взлома подписей.

Возможности

Поддерживаемые типы контента: видео + изображения с текстом (длинные статьи); для всех извлекаются заголовок / автор / данные о взаимодействии / обложка / длительность.

Принцип работы

Веб-интерфейс 抖音 защищён подписями времени выполнения, поэтому подделать вызовы API напрямую невозможно. Этот сервис использует:

1. Запускает настоящий Chrome через Playwright (постоянный profile);

2. Один раз выполняется вход по QR-коду, session cookie сохраняется локально;

3. Управляет UI страницы (клик по вкладке «Избранное», затем по подвкладке «Папки избранного»), перехватывает XHR-ответы;

4. Разбирает и возвращает структурированные данные.

Проверенные интерфейсы (2026-08):

• Список папок избранного: GET /aweme/v1/web/collects/list/

• Содержимое папки избранного: GET /aweme/v1/web/collects/video/list/?collects_id=...&cursor=0&count=10

• Всё избранное: POST /aweme/v1/web/aweme/listcollection/ (cursor в теле POST)

Установка

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

pip install -e .
playwright install chromium

Конфигурация (WorkBuddy / Claude Desktop)

Добавьте в конфигурацию MCP (например, ~/.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 — это место хранения profile браузера (состояние входа). Не включайте его в систему контроля версий.

Первое использование

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

Состояние входа сохраняется между сессиями; обычно повторный вход по QR-коду требуется раз в несколько недель.

Тестирование

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

Примечания и известные ограничения

• Определение состояния входа основано на session cookie (sessionid / sessionid_ss / sid_guard / sid_tt), не используйте элементы DOM (на главной странице 抖音 без входа также много аватаров авторов, это приведёт к ложным срабатываниям).

• Главная страница 抖音 никогда не достигает состояния networkidle, поэтому для всей навигации используется domcontentloaded.

• Пагинация на странице избранного запускается реальным колесом мыши (сначала mouse.move в область контента, затем wheel); window.scrollTo не работает.

• Вкладку «Избранное» необходимо активировать кликом; параметр URL ?showTab=favorite сам по себе не действует.

• get_video_detail может быть временно недоступен из-за изменений в API деталей 抖音.

Отказ от ответственности

Этот проект предназначен только для личного обучения, исследований и обработки данных. Используя этот инструмент, вы подтверждаете:

• Вы получаете доступ только к данным аккаунта 抖音, к которым у вас есть полные права доступа;

• Вы не будете использовать этот инструмент для массового сбора данных, продажи данных, накрутки или других незаконных/нарушающих правил действий;

• Вы понимаете, что API 抖音 может меняться в любое время, что может привести к временной неработоспособности инструмента.

Любые последствия, возникшие из-за нарушения вышеуказанных условий или соответствующих законов и нормативных актов, пользователь берёт на себя.

Лицензия

MIT