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.

⚠️ 개인 승인 용도: 이 도구는 현재 로그인된 계정의 즐겨찾기 데이터만 읽으며, 타인 데이터 수집, 캡차 우회 또는 서명 해독 기능을 제공하지 않습니다.

기능

지원 콘텐츠 유형: 동영상 + 이미지 텍스트(장문), 제목 / 작성자 / 상호작용 데이터 / 표지 / 재생 시간을 모두 추출할 수 있습니다.

작동 원리

抖音 웹 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