Douyin MCP
抖音 MCP (Model Context Protocol) 服务器，为 AI 助手提供访问抖音数据的能力。
项目简介
Douyin MCP 是一个基于 MCP 协议的服务器，允许 AI 助手（如 Claude）直接与抖音平台交互。通过本项目，AI 可以搜索视频、获取视频详情、读取评论、查看用户信息等。
核心特性
- 本地签名：内置 JavaScript 签名算法，通过 V8 引擎（py_mini_racer）本地生成
a_bogus签名，无需外部签名服务 - 完整功能：提供 8 个工具覆盖抖音主要数据获取场景
- 简单配置：仅需提供抖音 Cookies 即可使用
- 类型安全：完整的 Python 类型注解和数据模型
功能列表
| 工具 | 功能描述 | 参数 | |------|----------|------| | check_login_status | 检查登录状态 | 无 | | search_videos | 按关键词搜索视频 | keyword, offset, count, 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 | 获取推荐视频流 | tag, count, refresh_index |
环境要求
- Python 3.14+
- uv 包管理器（推荐）
- 有效的抖音登录 Cookies
安装
# 克隆仓库
git clone https://github.com/yourusername/douyinmcp.git
cd douyinmcp
# 安装依赖
uv sync配置
Cookie 配置
本项目使用 cookies.txt 文件配置 Cookie，不使用环境变量（避免特殊字符导致的问题）。
配置步骤：
- 在项目根目录创建
cookies.txt文件 - 将抖音 Cookie 字符串粘贴到文件中（单行，无需引号）
# 创建 cookies.txt 文件
touch cookies.txt
# 编辑文件，粘贴你的 Cookie
vim cookies.txt获取 Cookies
- 打开浏览器，访问 https://www.douyin.com
- 登录你的抖音账号
- 按 F12 打开开发者工具
- 进入 Application → Cookies → https://www.douyin.com
- 复制所有 Cookie（格式：
key1=value1; key2=value2; ...） - 粘贴到
cookies.txt文件中
或者使用浏览器插件（如 EditThisCookie）导出 Cookie 字符串。
cookies.txt 文件示例： `` sessionid=abc123; ttwid=xxx; passport_csrf_token=yyy; ... ``
注意：Cookie 必须是单行文本，不要包含换行符。
使用方法
直接运行
# 确保 cookies.txt 文件存在
uv run python main.py配置 Claude Desktop
在 claude_desktop_config.json 中添加：
{
"mcpServers": {
"douyin": {
"command": "uv",
"args": ["run", "--directory", "/path/to/douyinmcp", "python", "main.py"]
}
}
}注意：无需配置环境变量，Cookie 从项目根目录的
cookies.txt文件读取。
配置 Claude Code
在 .mcp.json 中添加 MCP 服务器配置：
{
"mcpServers": {
"douyin": {
"command": "uv",
"args": ["run", "--directory", "/path/to/douyinmcp", "python", "main.py"]
}
}
}工具详细说明
1. check_login_status - 检查登录状态
检查当前 Cookie 是否有效登录。
# 返回示例
{"logged_in": True}2. search_videos - 搜索视频
按关键词搜索抖音视频。
| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | keyword | str | 搜索关键词 | 必填 | | offset | int | 分页偏移 | 0 | | count | int | 每页数量 | 10 | | search_channel | str | 搜索类型：general/video/user/live | general | | sort_type | int | 排序：0-综合, 1-最多点赞, 2-最新 | 0 | | publish_time | int | 时间筛选：0-不限, 1-1天内, 7-1周内, 180-半年内 | 0 |
# 搜索美食视频，按点赞数排序
search_videos(keyword="美食", sort_type=1, count=20)3. get_video_detail - 获取视频详情
通过视频 ID 获取视频详细信息。
| 参数 | 类型 | 说明 | |------|------|------| | aweme_id | str | 视频 ID |
# 获取指定视频详情
get_video_detail(aweme_id="7590719110745525567")
# 返回信息包括：
# - 标题、描述
# - 点赞数、评论数、分享数、收藏数
# - 作者信息
# - 视频封面、下载地址4. get_video_comments - 获取视频评论
获取视频的评论列表。
| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | aweme_id | str | 视频 ID | 必填 | | cursor | int | 分页游标 | 0 | | count | int | 每页数量 | 20 |
# 获取视频评论
get_video_comments(aweme_id="7590719110745525567", count=50)5. get_sub_comments - 获取评论回复
获取某条评论的回复列表。
| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | comment_id | str | 评论 ID | 必填 | | cursor | int | 分页游标 | 0 | | count | int | 每页数量 | 20 |
# 获取评论的回复
get_sub_comments(comment_id="7590992888545395462")6. get_user_info - 获取用户信息
获取用户的个人资料。
| 参数 | 类型 | 说明 | |------|------|------| | sec_user_id | str | 用户安全 ID（以 MS4wLjABAAAA 开头）|
# 获取用户信息
get_user_info(sec_user_id="MS4wLjABAAAAG35eRUkDUlhVctlBVKNxjbbqw4Bu...")
# 返回信息包括：
# - 昵称、签名、头像
# - 粉丝数、关注数
# - 获赞数、作品数
# - IP 属地7. get_user_posts - 获取用户作品
获取用户发布的视频列表。
| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | sec_user_id | str | 用户安全 ID | 必填 | | max_cursor | str | 分页游标 | "0" | | count | int | 每页数量 | 18 |
# 获取用户的视频作品
get_user_posts(sec_user_id="MS4wLjABAAAA...", count=30)8. get_homefeed - 获取推荐视频
获取首页推荐视频流。
| 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | tag | str | 内容分类 | "all" | | count | int | 获取数量 | 20 | | refresh_index | int | 刷新索引 | 0 |
支持的分类标签：
all- 全部knowledge- 知识sports- 体育auto- 汽车anime- 二次元game- 游戏movie- 影视life_vlog- 生活travel- 旅行mini_drama- 短剧food- 美食agriculture- 三农music- 音乐animal- 萌宠parenting- 亲子fashion- 时尚
# 获取游戏类推荐视频
get_homefeed(tag="game", count=20)项目结构
douyinmcp/
├── src/
│ ├── __init__.py # 包初始化
│ ├── models.py # 数据模型定义
│ ├── token_manager.py # Token 生成（msToken, webid, verifyFp）
│ ├── sign.py # 本地签名模块（V8 引擎）
│ ├── douyin.js # 签名算法（JavaScript）
│ ├── client.py # API 客户端实现
│ └── server.py # MCP 服务器及工具定义
├── tests/
│ ├── __init__.py
│ └── test_all.py # 综合测试套件
├── doc/
│ └── API.md # API 接口文档
├── main.py # 程序入口
├── pyproject.toml # 项目配置
├── cookies.txt # Cookie 文件（需自行创建）
├── CHANGELOG # 变更日志
└── README.md # 本文档测试
运行综合测试验证所有功能：
# 确保 cookies.txt 存在
uv run python tests/test_all.py测试输出示例：
============================================================
Douyin MCP - Comprehensive Test Suite
============================================================
Testing check_login_status...
✓ check_login_status: logged_in=True
Testing search_videos...
✓ search_videos: Found 5 results
Testing get_video_detail...
✓ get_video_detail: Got video: 《给大家讲讲...》
Testing get_video_comments...
✓ get_video_comments: Got 10 comments
Testing get_sub_comments...
✓ get_sub_comments: Got 1 replies
Testing get_user_info...
✓ get_user_info: Got user: 大阳
Testing get_user_posts...
✓ get_user_posts: Got 10 posts
Testing get_homefeed...
✓ get_homefeed: Got 2 videos from feed
Results: 8/8 tests passed
============================================================技术实现
签名机制
抖音 Web API 使用 a_bogus 参数进行请求签名验证。本项目通过以下方式实现本地签名：
- 使用
py_mini_racer库提供 V8 JavaScript 引擎 - 加载
douyin.js签名算法 - 构建完整的浏览器环境 polyfills（document, navigator, window 等）
- 调用
get_abogus()函数生成签名
Token 生成
- msToken: 128 字符的验证 Token，支持从字节跳动 API 获取或本地生成
- webid: 19 位数字 ID，支持从服务器获取或本地 UUID 算法生成
- verifyFp / s_v_web_id: 指纹验证参数，使用 Base36 时间戳 + UUID 格式
请求参数
每个请求包含 31 个通用参数，模拟真实浏览器环境：
- 设备信息（platform, cpu_core_num, device_memory）
- 浏览器信息（browser_name, browser_version, engine_name）
- 屏幕信息（screen_width, screen_height）
- 网络信息（downlink, effective_type, round_trip_time）
常见问题
Q: Cookie 多久需要更新？
A: 抖音 Cookie 通常有效期较长，但如果遇到 logged_in=False 或请求失败，需要重新获取 Cookie 并更新 cookies.txt 文件。
Q: 为什么不使用环境变量配置 Cookie？
A: 抖音 Cookie 包含大量特殊字符（如 =、;、% 等），在环境变量中配置容易出现解析问题。使用文件配置更可靠。
Q: cookies.txt 文件放在哪里？
A: 放在项目根目录（与 main.py 同级目录）。
Q: 为什么 get_homefeed 返回的视频数量较少？
A: 推荐接口返回的数量取决于抖音服务器，可能需要多次调用并增加 refresh_index 来获取更多内容。
Q: 遇到签名错误怎么办？
A: 签名模块会自动重置 JavaScript 上下文。如果持续失败，请检查 douyin.js 文件是否完整。
Q: 支持哪些 Python 版本？
A: 项目使用 Python 3.14+ 特性，建议使用最新版本。
API 文档
详细的 API 接口文档请参阅 doc/API.md。
依赖项
fastmcp- MCP 服务器框架httpx- 异步 HTTP 客户端py-mini-racer- V8 JavaScript 引擎
许可证
MIT License
免责声明
本项目仅供学习和研究使用。使用本项目获取的数据应遵守抖音平台的服务条款和相关法律法规。请勿将本项目用于任何商业用途或违法行为。
