抖音运营 MCP（douyin-ops-mcp）

⚠️ 使用前必读

本项目是跑在你自己电脑上的个人工具，与抖音/字节跳动无任何关联、未获授权。 它通过驱动你本机 Chrome 完成操作，等同于你本人操作，因此：

• 只能用于运营你本人拥有或已获授权的账号，发布你拥有权利的内容；

• 禁止用于刷量、批量养号、规避平台安全机制、大规模抓取或转售数据、以及任何违法违规用途；

• 自动化操作可能违反平台协议，存在限流、封号风险；发布前请务必 dryRun: true 自行审核；

• 登录 cookie 存在本机 data/（已 gitignore），请自行保管。

完整条款见 DISCLAIMER.md（这不是法律意见，商业用途请咨询律师）。

仓库：https://github.com/kungful/douyin-ops-mcp · 配套 Pi 技能：~/.pi/agent/skills/douyin-ops

一个给 agent 用的抖音运营工具：采集解析 → 爆款拆解 → 内容排期 → 自动发布 → 数据复盘，全链路。

融合了四个上游项目各自的长处，但代码是重写的（因为它们的核心部分在国内网络下都跑不通或已经过时）：

关键设计：为什么必须有浏览器

抖音 Web 的每个 /aweme/v1/web/* 请求都要带 a_bogus 签名，算法藏在字节码 VM 里（bdms.js）， 而且站点自己已经给 fetch 打了补丁：任何从抖音页面上下文里发出的 /aweme/v1/web/* 请求， a_bogus、msToken、指纹 cookie 全都会自动补齐。

所以本项目的接口调用方式是——在真实 Chrome 的抖音标签页里 page.evaluate(fetch(...))：

✅ 免登录：作品详情、用户资料、作品列表、评论、热榜、热点视频流
❌ 需要登录：搜索、发布、我的作品数据、评论/通知、点赞评论等写操作

代价是必须有浏览器；好处是签名规则变了不用跟（上游那个项目为此维护了 4000 行签名代码， 还需要 cookie 池 + 代理池）。而"运营账号"本来就得登录浏览器，所以这个代价是白送的。

Related MCP server: affiliate-marketplace-mcp

快速开始

cd "C:\Users\hua\Documents\备份代码\douyin-mcp-fusion"
npm install                 # 只依赖 playwright-core，用系统 Chrome，不下载浏览器
npm run smoke               # 自检：热榜/解析/评论/登录态（会弹一次 Chrome 窗口）
npm run smoke -- --full     # 再跑下载 + 文案提取

注册到 pi（已写入 ~/.pi/agent/mcp.json）后，在 pi 里执行 /reload 即可看到 29 个工具。

首次使用先登录一次（登录态存进 data/browser-profile，之后不用再扫）：

douyin_login_qrcode({ waitSeconds: 120 })   # 抓二维码 → 用户用抖音 App 扫码
douyin_login_status({})                     # 确认 www / 创作者中心 都登录了

工具清单（29 个）

采集 · 免登录

登录 · 发布

数据 · 互动

排期 · 自动化

常驻发布：npm run queue（或双击 start-queue.cmd），每 30 秒检查一次队列，到点自动发。

一条完整的运营链路长这样

1) 选题   douyin_trending({board:'hot', videos:10})
          → 今天有什么在涨；挑 3 个和你赛道交叉的

2) 对标   douyin_search({keyword:'咖啡拉花'})  → douyin_breakdown({target: 爆款链接})
          → 搞清楚它为什么起：钩子句式、结构、热评里的真实需求

3) 采集   douyin_batch_download({source:'user', target:'竞品主页', limit:10})
          → 素材库；配 douyin_transcribe 拆口播

4) 创作   用 videostudio 技能剪片（或本地已有成片）
          douyin_local_check({file})  → 规格过不了就别发了

5) 发布   douyin_publish_video({file, title, desc, topics, dryRun:true})
          → 看预览截图确认 → dryRun:false 真发
          或者 douyin_queue_add 排进一周的档期

6) 复盘   douyin_my_videos({limit:20}) + douyin_account_overview({})
          → 哪条值得投流/切片；douyin_notifications 及时回评论

环境变量

没有 ASR key 也能用：会自动落到本地 faster-whisper（首次从 ModelScope 下模型，small 约 484MB）。

反爬与稳定性（踩过的坑）

• 无头浏览器必然吃滑块。默认有头；用户能看到 Chrome 窗口，需要过验证码时手动过一下，之后 profile 里就干净了。

• 命中验证码/登录墙/风控时，工具不会静默失败，而是返回带截图路径的明确提示（BrowserBlockedError）。

• 频率：批量采集每条间隔 1.2~2.7 秒随机；一次 limit 建议 ≤30。

• version_code=290100 是当前 Web 客户端版本，抖音大版本升级后可能需要更新 src/douyin/params.js。

• 公开接口的 play_count 对别人的作品永远是 0（不是真 0 播放）；真实播放量只有创作者中心有 → 用 douyin_my_videos。

目录结构

src/
  server.js              MCP stdio 服务（手写 JSON-RPC，不依赖 SDK）
  tools/index.js         29 个工具的定义与描述（描述是写给模型看的）
  browser/manager.js     持久化 Chrome（唯一 profile）+ 页面池
  browser/pagekit.js     导航、验证码/风控识别、多候选选择器点击填写
  douyin/client.js       ★ 页内 fetch（站点自动签名）+ 错误码语义
  douyin/params.js       接口参数表
  douyin/parse.js        链接/ID/主页 定位 + 详情/列表/搜索/热榜
  douyin/normalize.js    aweme/user/comment → 运营关心的字段
  douyin/media.js        下载、ffmpeg 探针、抽帧、发布规格校验
  douyin/asr.js          ASR 三级降级
  douyin/breakdown.js    爆款拆解
  creator/login.js       扫码登录、登录态判定、会话预热
  creator/publish.js     视频/图文发布（多候选选择器 + dryRun + 逐步报告）
  creator/stats.js       我的作品 / 账号概览 / 单条数据
  creator/interactions.js 评论、回复、点赞、通知
  creator/scrape.js      创作者中心表格抓取与指标解析
  store.js               队列 / 素材库 / 下载清单（原子写 JSON）
python/asr_whisper.py    本地 faster-whisper（ModelScope 下模型）
scripts/                 smoke / protocol-test / login / queue-daemon

实测记录（2026-10-31，账号「苏维埃」）

node scripts/test-suite.js all 的成绩：12/14 通过（报告在 data/test-report-all.md）。

踩过并已修掉的坑：

1. 上传页是 React，input[type=file] 要等挂载完才出现（约 10s）。

2. 发布编辑页真实路径是 /content/post/video，不是 /content/publish。

3. 标题要 .type() 并读回 inputValue()；描述必须鼠标点进 .zone-container 再 insertText（点 locator 不聚焦，第一版就这么发出去一条空描述）。

4. 图文必须先点「发布图文」切模式，否则拿到的是只收 video/* 的单文件 input。

5. 话题走页面 #添加话题 → 输入 → 点联想项，并读回校验。

6. 页面 innerText 里常驻"上传中"文案，不能拿来判断上传状态；要用发布按钮状态 + 预览视频 duration。

7. 点完发布 ≠ 发完：抖音先提交再后台上传（右下角百分比），上传没走完关浏览器就断了。

8. 定时发布是 <label><input type=checkbox><span>定时发布</span></label> 的自定义单选，getByText().click() 会被 span 拦截超时，只能 label.click()。

9. 抖音大量 data-e2e 节点是 0×0 的隐藏副本：waitForSelector 默认等 visible 会一直超时，必须 state:'attached'。

10. 封面弹窗装不下 Esc / 取消，只有右上角那颗 svg X 能关；关不掉会挡住"发布"按钮。

11. Web 写接口（comment/publish、commit/item/digg）直接被风控：status_code=8 / 4，所以互动走 UI。

12. 连续高频操作会被限流（页面 30s 渲染不出内容）——测试的时候要把节奏放慢。

已知限制

• 创作者中心改版后选择器会失效。第一次发请务必 dryRun: true 看截图；失败时返回的 steps 会指出卡在哪一步，改那一步的选择器即可。

• 自定义封面不可用（平台要人工裁切）：建议不传 cover，用平台自动封面；工具会在失败时自动关掉弹窗，不影响发布。

• 点赞偶发 no-op：页面只暴露 0×0 的隐藏节点，点了没反应时重试一次即可；批量养号别指望它。

• 抖音会限流连续高频操作（页面 30s 渲染不出来），批量采集/互动要放慢节奏。

• 创作者中心的表格结构随版本变化，douyin_my_videos 解析不到时会退回返回页面文本，供人工定位。

• 只支持抖音（中国区），不含 TikTok。

• 不做刷量、不做多账号矩阵（同一 profile 只能登一个号；多号就复制一份 data 目录并改 DOUYIN_DATA）。

许可

• 代码许可：MIT（见 LICENSE）

• 使用边界与免责：DISCLAIMER.md —— 请在使用前读一遍

• 第三方组件与知识来源的完整清单：NOTICE

致谢

本项目代码为自研。接口参数/数据结构的知识来源见上表（上游均为 Apache-2.0，只借鉴了参数名、 数据字段和工程判断，没有拷贝其代码）。a_bogus 的成因分析出自上游 docs/design/17-signature-reversing.md — 但本项目没有实现签名算法，用的是"在页面里让站点自己签"这条更稳的路。