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.

⚠️ 个人授权使用：本工具仅读取当前登录账号的收藏夹数据，不提供他人数据抓取、验证码绕过或签名破解功能。

功能特性

工具	说明
douyin_login_start	打开有头 Chrome 扫码登录抖音（会话保存在本地 profile）
douyin_login_status	检查当前 session 是否有效（基于 sessionid cookie）
douyin_logout	清空本地浏览器 profile
douyin_health_check	健康检查
get_self_user_info	获取当前登录账号基本信息（昵称/uid/粉丝/关注/获赞）
list_collection_videos	拉取默认"收藏"夹的视频列表
list_collects	列出所有收藏夹（专辑）：id、名称、视频数量
get_collect_videos	拉取指定收藏夹（专辑）内的视频/图文
get_video_detail	获取单条视频详情与互动数据

支持内容类型：视频 + 图文（长文章），均能提取标题 / 作者 / 互动数据 / 封面 / 时长。

工作原理

抖音 Web 接口带有运行时签名保护，无法直接伪造 API 调用。本服务采用：

1. 用 Playwright 启动真实 Chrome（持久化 profile）；
2. 扫码登录一次，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 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>"})

登录态跨会话持久化，通常数周才需重新扫码一次。

测试

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 可能因抖音改版详情接口而暂时不可用。

免责声明

本项目仅用于个人学习、研究和数据整理。使用本工具即表示您确认：

• 您仅访问自己拥有完整访问权限的抖音账号数据；
• 您不会将本工具用于批量爬取、数据贩卖、刷量或其他违法/违规行为；
• 您理解抖音接口可能随时变化，导致工具暂时失效。

如因违反上述条款或相关法律法规造成任何后果，由使用者自行承担。

许可证

MIT