# douyin-favorites-mcp · 抖音收藏夹 MCP 服务

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**抖音收藏夹 / 抖音收藏 的 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）

## 安装

```bash
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`）：

```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（登录态）的存放位置，请勿纳入版本控制。

## 首次使用

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

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

## 测试

```bash
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