douyin-favorites-mcp · 抖音コレクション MCP サービス

抖音コレクション / 抖音のお気に入り の Model Context Protocol (MCP) サーバー —— ログイン状態のブラウザセッションを通じて、自分のアカウントの抖音のお気に入り（デフォルトのお気に入り）、コレクション / アルバム（例：「学習」）を読み取り、構造化データを AI アシスタント（Claude / WorkBuddy など）にエクスポートして利用します。

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.

⚠️ 個人利用の認可：本ツールは現在ログインしているアカウントのコレクションデータのみを読み取り、他人のデータスクレイピング、CAPTCHA 回避、署名クラック機能は提供しません。

機能

対応コンテンツタイプ：動画 + 画像・テキスト（長文記事）。タイトル / 作者 / インタラクションデータ / カバー画像 / 再生時間を抽出できます。

動作原理

抖音の Web API には実行時署名保護があり、API 呼び出しを直接偽造することはできません。本サービスでは次の方法を採用しています：

1. Playwright で実際の Chrome を起動（永続化 profile）；

2. QR コードで一度ログインし、session cookie をローカルに保存；

3. ページ UI を操作（「お気に入り」タブをクリックし、「コレクション」サブタブをクリック）、XHR レスポンスを傍受；

4. 解析して構造化データを返す。

検証済みの API（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 body 内）

インストール

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 は無効です。

• 「お気に入り」タブはクリックでトリガーする必要があります。?showTab=favorite URL パラメータ自体は無効です。

• get_video_detail は、抖音の詳細 API のリニューアルにより一時的に利用できない場合があります。

免責事項

本プロジェクトは個人の学習、研究、データ整理のみを目的としています。本ツールを使用することで、以下を確認したことになります：

• 完全なアクセス権限を持つ自分の抖音アカウントのデータのみにアクセスすること；

• 本ツールを大量スクレイピング、データ販売、不正な水増し、その他の違法・規約違反行為に使用しないこと；

• 抖音の API は随時変更され、ツールが一時的に使用できなくなる可能性があることを理解していること。

上記の条項または関連する法律・規制に違反したことによるいかなる結果も、利用者自身が負担するものとします。

ライセンス

MIT