# Douyin MCP 🎬

抖音 (Douyin / 中国版 TikTok) MCP 服务器 —— 让 Claude 等 AI 助手直接访问抖音数据:搜索视频、视频详情、评论、用户资料、推荐流。

基于 [FastMCP](https://github.com/jlowin/fastmcp) + Python,内置本地签名,不依赖任何外部服务。

## ✨ 特性

- **本地签名**:内置 JavaScript 签名算法,通过 V8 引擎 ([py-mini-racer](https://github.com/sqreen/PyMiniRacer)) 本地生成 `a_bogus` 签名,无需外部签名服务
- **8 个工具**:覆盖抖音主要数据获取场景(搜索 / 详情 / 评论 / 用户 / 推荐流)
- **零配置复杂度**:仅需提供抖音 Cookies 即可使用
- **类型安全**:完整的 Python 类型注解和 dataclass 数据模型

## 🛠 工具一览

| 工具 | 功能 | 关键参数 |
|------|------|----------|
| `check_login_status` | 检查当前登录态 | 无 |
| `search_videos` | 按关键词搜索视频 | keyword, offset, count, search_channel, sort_type, publish_time |
| `get_video_detail` | 获取视频详情(**含播放直链、封面、图文帖图片直链**) | aweme_id |
| `get_video_comments` | 获取视频评论(分页) | aweme_id, cursor, count |
| `get_sub_comments` | 获取评论回复 | comment_id, cursor, count |
| `get_user_info` | 获取用户资料(昵称、粉丝数等) | sec_user_id |
| `get_user_posts` | 获取用户发布的视频列表(带播放直链) | sec_user_id, max_cursor, count |
| `get_homefeed` | 获取推荐流(支持 16 个内容分类) | tag, count, refresh_index |

> **关于「下载」**:本项目提供获取**视频播放直链**的能力 —— `get_video_detail` 返回的 `video_download_url` 即无水印播放地址,图文帖返回 `images` 图片直链。拿到直链后可用 `curl`、浏览器或任意下载器自行下载,项目本身不包含「下载到本地文件」的工具。

## 📦 环境要求

- Python 3.14+
- [uv](https://github.com/astral-sh/uv) 包管理器(推荐)
- 有效的抖音登录 Cookies

## 🚀 安装

```bash
# 克隆仓库
git clone https://github.com/kaleburannengsha-hue/douyin-mcp.git
cd douyin-mcp

# 安装依赖
uv sync
```

## 🍪 Cookie 配置

1. 浏览器登录 [www.douyin.com](https://www.douyin.com)
2. 按 F12 → 应用 (Application) → Cookies → `https://www.douyin.com`
3. 将全部 Cookie 拼接为一行 `key1=value1; key2=value2; ...`(用分号+空格分隔),粘贴到项目根目录的 `cookies.txt`

```bash
# 创建 cookies.txt(参考 cookies.txt.example)
touch cookies.txt
# 将 Cookie 字符串粘贴进去(单行,无需引号)
```

> ⚠️ **安全提醒**:`cookies.txt` 已在 `.gitignore` 中排除。Cookie 等同账号凭证,**泄露 = 账号被盗风险**,切勿提交到任何仓库或分享给他人。

## 🔌 接入 MCP 客户端

### Claude Desktop

编辑 Claude Desktop 的 `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "douyin": {
      "command": "uv",
      "args": ["run", "--directory", "D:/path/to/douyin-mcp", "douyinmcp"]
    }
  }
}
```

- Windows 配置文件路径:`%APPDATA%\Claude\claude_desktop_config.json`
- macOS 配置文件路径:`~/Library/Application Support/Claude/claude_desktop_config.json`
- `--directory` 指向本仓库路径,uv 会自动读取 `.python-version` 创建虚拟环境

### Claude Code / Codex

```bash
claude mcp add douyin -- uv run --directory /path/to/douyin-mcp douyinmcp
```

### 直接运行

```bash
uv run douyinmcp   # 以 stdio 方式启动 MCP 服务器
```

## 🧪 测试

```bash
uv run python tests/test_all.py
```

测试覆盖全部 8 个工具,需要先配置好 `cookies.txt`。

## 🏗 项目结构

```
douyin_mcp/
├── main.py              # 入口:启动 MCP 服务器
├── pyproject.toml       # 项目配置(uv)
├── cookies.txt.example  # Cookie 配置模板
├── src/
│   ├── server.py        # FastMCP 服务器与 8 个工具定义
│   ├── client.py        # 抖音 API 客户端
│   ├── models.py        # dataclass 数据模型
│   ├── sign.py          # 本地 a_bogus 签名(V8 引擎)
│   ├── douyin.js        # 内嵌签名算法 JS
│   └── token_manager.py # msToken / webid / verify_fp 生成
├── doc/
│   └── API.md           # 底层接口参考文档(MediaCrawlerPro 整理,部分章节为旧版签名服务,已改用本地签名)
└── tests/
    └── test_all.py      # 8 工具全量测试
```

## ⚠️ 免责声明

- 本项目**仅供学习研究使用**,请勿用于商业用途或大规模抓取
- 请遵守抖音平台服务条款及相关法律法规,尊重创作者版权
- 本项目与抖音 / 字节跳动无任何关联,非官方项目
- 平台接口与风控策略可能随时变化,可能导致功能失效或账号受限,使用风险自负

## 📄 License

[MIT](LICENSE)