douyin-favorites-mcp · Douyin Favorites MCP Service

Model Context Protocol (MCP) server for Douyin Favorites / Douyin Collections — reads the Douyin favorites (default favorites), collection folders / albums (e.g., "Learning") of your own account via a logged-in browser session, and exports structured data for AI assistants (Claude / WorkBuddy, etc.) to use.

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

⚠️ Personal authorized use: This tool only reads the favorites data of the currently logged-in account; it does not provide scraping of others' data, CAPTCHA bypass, or signature cracking.

Features

Supported content types: videos + image-text posts (long articles); both allow extracting title / author / interaction data / cover / duration.

How It Works

The Douyin web API has runtime signature protection, so API calls cannot be directly forged. This service uses:

1. Use Playwright to launch a real Chrome (persistent profile);

2. Scan the QR code to log in once; the session cookie is saved locally;

3. Drive the page UI (click the "Favorites" tab, then the "Collection folders" sub-tab), intercept XHR responses;

4. Parse and return structured data.

Verified endpoints (2026-08):

• Collection folder list: GET /aweme/v1/web/collects/list/

• Collection folder contents: GET /aweme/v1/web/collects/video/list/?collects_id=...&cursor=0&count=10

• All favorites: POST /aweme/v1/web/aweme/listcollection/ (cursor is in the POST body)

Installation

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

pip install -e .
playwright install chromium

Configuration (WorkBuddy / Claude Desktop)

Add to the MCP configuration (e.g., ~/.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 is the location where the browser profile (login state) is stored; do not include it in version control.

First-Time Usage

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

The login state persists across sessions; you usually only need to scan the QR code again every few weeks.

Testing

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

Notes and Known Limitations

• Login state detection is based on session cookies (sessionid / sessionid_ss / sid_guard / sid_tt); do not use DOM elements to determine it (the Douyin homepage shows many author avatars even when not logged in, which would cause false positives).

• The Douyin homepage never reaches networkidle; use domcontentloaded for all navigation.

• Pagination on the favorites page is triggered by the real mouse wheel (first mouse.move to the content area, then wheel); window.scrollTo does not work.

• The "Favorites" tab must be triggered by clicking; the ?showTab=favorite URL parameter alone has no effect.

• get_video_detail may be temporarily unavailable because Douyin has revamped its detail API.

Disclaimer

This project is for personal learning, research, and data organization only. By using this tool, you confirm that:

• You only access data from Douyin accounts over which you have full access rights;

• You will not use this tool for bulk scraping, data resale, engagement boosting, or other illegal/non-compliant activities;

• You understand that Douyin's APIs may change at any time, causing the tool to become temporarily non-functional.

Any consequences arising from violation of the above terms or applicable laws and regulations shall be borne by the user.

License

MIT