1. 项目概述一个面向AI Agent的抖音自动化发布工具如果你正在研究如何让AI Agent比如Claude Desktop、Cursor等具备自动化发布抖音内容的能力那么你找对地方了。douyin-upload-mcp-skill这个项目本质上是一个“翻译官”和“执行者”。它通过MCPModel Context Protocol协议将复杂的抖音创作者平台网页操作封装成AI可以理解和调用的标准化工具。简单来说它让AI拥有了“打开浏览器”、“登录抖音”、“上传视频”、“填写文案”、“点击发布”这一系列操作的真实能力。这个项目的核心价值在于“全链路自动化”和“AI原生集成”。它不是为了写一个简单的爬虫脚本而是为了构建一个能被AI Agent无缝调用的服务。想象一下你只需要对AI说“帮我把这个视频发到抖音标题是‘周末骑行Vlog’”AI就能理解你的意图并调用这个技能背后的工具自动完成从登录到发布的全部流程。这对于内容创作者、营销团队或者任何需要批量、定时发布内容的场景来说是一个巨大的效率提升。项目采用了CDPChrome DevTools Protocol作为底层技术这意味着它直接与Chrome浏览器内核对话模拟真实用户操作稳定性和兼容性远高于传统的基于DOM操作的自动化工具。同时它通过独立的Daemon进程管理浏览器生命周期解决了浏览器实例常驻内存、登录态保持等工程化难题。接下来我将为你深入拆解这个项目的设计思路、技术实现细节并分享在实际部署和调试中积累的一手经验。2. 核心架构与设计思路拆解2.1 为什么选择 MCP CDP 的技术栈在决定自动化方案时我们面临几个选择Selenium、Playwright、Puppeteer或者更底层的CDP。这个项目选择了Puppeteer-core CDP的路径并在此基础上封装为MCP服务这是一个经过深思熟虑的架构决策。首先关于自动化框架的选择。Playwright和Puppeteer都是优秀的浏览器自动化库。本项目选择Puppeteer-core而非完整版Puppeteer核心原因是“轻量”与“控制”。Puppeteer-core只包含连接CDP的核心逻辑不捆绑特定版本的Chromium。这允许我们自由指定或复用系统中已安装的任何Chrome/Edge/Chromium浏览器对于部署环境更加友好。更重要的是通过CDP协议我们可以获得对浏览器最底层的控制能力这对于实现精细化的“人类行为模拟”如随机移动轨迹、间隔点击和应对复杂的反爬检测至关重要。其次关于协议层的选择——MCP。MCP是由Anthropic提出的一种协议旨在为AI模型提供访问外部工具和数据的标准方式。将抖音自动化功能封装成MCP技能意味着任何兼容MCP的AI客户端如Claude Desktop都可以直接发现并调用这些工具无需为每个AI平台单独开发插件。这实现了“一次开发多处集成”的效果。douyin_publish_video、douyin_check_login这些工具对AI来说就像get_weather、send_email一样是清晰、可调用的函数极大降低了AI应用开发的复杂度。最后关于架构分层。项目的分层非常清晰这是保证可维护性和扩展性的关键。协议层MCP Server负责与AI客户端通信解析请求调用对应的业务函数。业务层Douyin Ops编排抖音发布的核心业务流程例如“上传-等待转码-选择封面-填写信息-发布”这一连串操作。原子操作层Operator封装所有针对网页元素的底层CDP操作定位、点击、输入、滚动并在这里注入“人类行为模拟”逻辑。连接层Browser负责与浏览器Daemon建立连接获取可用的浏览器实例Page对象。守护进程层Daemon独立进程管理浏览器的启动、保持和按需销毁。这是项目的精髓之一解决了浏览器常驻带来的资源浪费和状态管理难题。这种分层设计使得每一层的职责单一调试起来也非常方便。比如当发布失败时我们可以先通过douyin_probe工具检查页面元素状态业务层如果元素找不到再检查Operator层的定位逻辑最后可以检查Browser层连接是否正常。2.2 Daemon设计浏览器生命周期的智能管家浏览器自动化项目最头疼的问题之一就是浏览器实例的管理。如果每次调用都启动一个新浏览器耗时且无法保持登录态如果让浏览器一直开着又会白白占用大量内存和CPU资源。本项目的Daemon守护进程设计优雅地解决了这个问题。Daemon是一个独立的Node.js HTTP服务它扮演了“浏览器管家”的角色。它的工作流程如下按需启动当第一个请求例如来自MCP Server的调用到达Daemon时它才会启动浏览器进程。连接复用后续的所有请求都复用这个浏览器实例和同一个页面Page。这意味着登录状态、Cookies、本地存储都会被保留无需重复扫码登录。闲置销毁Daemon内部有一个计时器TTL默认为30分钟。如果在设定时间内没有任何请求它会自动关闭浏览器并结束自身进程释放系统资源。状态保持通过BROWSER_USER_DATA_DIR指定用户数据目录浏览器退出时会将Cookies、缓存等数据保存到此目录。下次启动时加载从而实现跨会话的登录态保持。一个重要的实践细节是用户数据目录的“克隆”行为。项目代码中有一个巧妙的设计首次运行时如果指定的用户数据目录为空它会尝试从系统默认的Chrome用户数据目录例如~/.config/google-chrome中复制一些基础数据。这样做的好处是如果你在常规Chrome中已经登录了抖音那么这个自动化浏览器在启动时可能就已经处于登录状态或者至少携带了你的浏览器指纹信息使得登录流程更加顺畅也显得更“像”一个真实用户。配置共享的考量Daemon监听一个HTTP端口默认40225这意味着同一台机器上的多个技能例如你可能有另一个处理微信公众平台的MCP技能可以配置连接到同一个Daemon共享同一个浏览器实例。这进一步优化了资源利用。但需要注意的是多个技能同时操作同一个Page可能会产生冲突好在抖音发布这类任务通常是串行的冲突风险较低。3. 核心功能实现与实操要点3.1 登录流程的自动化推进与状态机抖音的登录流程对于自动化来说是一个挑战因为它涉及扫码、短信验证等多步交互而MCP协议本身不支持在工具调用过程中进行实时的人机交互。项目通过一个状态机模式和多次调用的设计巧妙地解决了这个问题。douyin_check_login是这个流程的核心工具。它不仅仅检查“是否已登录”更是一个登录流程推进器。其内部实现了一个状态机大致如下qrcode二维码阶段工具首次被调用时会导航到登录页定位二维码并自动截图保存到OUTPUT_DIR。此时它返回phase: ‘qrcode’和二维码图片路径提示用户去扫码。这里有个关键点工具不会阻塞等待用户扫码而是立即返回。推进到下一步需要用户再次调用这个工具。sms_verification短信验证阶段用户扫码后抖音平台有时会要求短信验证。当工具被第二次调用时它会检测页面是否跳转到了短信验证页。如果是它会自动点击“获取短信验证码”按钮然后返回phase: ‘sms_verification’。sms_code_input输入验证码阶段第三次调用时工具检测到页面停留在等待输入验证码的状态返回phase: ‘sms_code_input’并等待调用者传入smsCode参数。logged_in已登录第四次调用时如果传入了正确的smsCode工具会填充验证码并完成登录最终返回phase: ‘logged_in’。实操心得处理登录超时与异常这个流程看似清晰但在实际网络环境或平台策略变化下容易出问题。我的经验是增加超时与重试在operator.js的locate函数中对关键元素如二维码、验证码输入框的查找必须设置合理的超时和重试机制。抖音页面加载有时受网络波动影响一次查找失败就放弃会导致流程中断。状态判断要冗余不能只依赖一个元素来判断阶段。例如判断是否在二维码页面除了检查二维码图片元素最好再检查一下页面URL或是否有“扫码登录”的文案进行交叉验证避免因页面元素加载顺序问题导致误判。做好持久化准备虽然Daemon会保持登录态但有时Cookies会过期。更稳健的做法是在成功登录后可以额外调用一次douyin_screenshot工具将登录成功后的创作者中心首页截图保存作为可视化的日志便于后期排查问题。3.2 视频发布从上传到发布的完整链条douyin_publish_video工具封装了视频发布的完整逻辑。理解这个链条中的每个环节及其“坑点”对于成功运行至关重要。1. 上传与转码等待这是最耗时的环节。工具通过CDP找到文件上传的input type”file”元素并将本地视频文件的绝对路径注入。之后抖音后台开始转码。这里的核心挑战是“如何知道转码何时完成”项目采用的方法是持续监测页面上的特定元素或文案变化例如“转码中…”提示消失或者“下一步”按钮从禁用变为可用。注意抖音的转码时间与视频大小、服务器负载有关可能从几十秒到几分钟不等。timeout参数默认为工具内部设置也可由调用方指定必须给足。我建议对于超过500MB的视频将超时时间设置为10分钟600000毫秒以上。2. AI封面推荐与选择转码完成后抖音通常会提供多个AI生成的封面选项。自动化脚本需要模拟人类行为等待封面缩略图加载完成然后随机选择其中一张或者可以预设选择第几张。这里有一个细节直接点击缩略图可能无效有时需要先点击“编辑封面”区域激活封面选择界面再进行点击。operator.js中的点击函数加入了随机延迟和微小移动轨迹就是为了更好地模拟人类操作绕过简单的点击检测。3. 标题与简介的填写通过CDP的Input.dispatchKeyEvent方法模拟键盘输入填入标题和描述。这里需要注意避免过快输入像打字一样每个字符之间应有随机延迟例如50-150毫秒。处理可能的敏感词检测如果标题中包含平台敏感词页面可能会实时弹出提示。一个健壮的实现应该在输入后等待一小段时间检查是否有错误提示框出现如果有则记录日志并中止发布流程。话题与的格式如果需要添加话题#xxx或某人需要确保输入格式正确并且“某人”在输入后能被成功联想并选中。这部分的自动化复杂度较高当前项目可能未做特别处理需要根据实际情况调整。4. 发布与结果确认点击“发布”按钮后并不代表万事大吉。需要等待发布成功的反馈例如出现“发布成功”的Toast提示或者页面跳转。工具应持续监测一段时间确认发布成功或者捕获明确的失败原因如“审核中”、“发布失败请重试”等并将最终状态返回给调用方。3.3 图文发布与反检测策略图文发布douyin_publish_imagetext的流程与视频类似但涉及多张图片上传。这里主要讲讲本项目的反检测策略这是自动化项目能否长期稳定的生命线。项目使用了puppeteer-extra-plugin-stealth插件这是一个行业标杆级的反检测方案。它做了大量工作来让Puppeteer控制的浏览器看起来更像普通用户隐藏WebDriver标志清除navigator.webdriver属性。修改浏览器指纹对navigator.plugins,navigator.languages等属性进行合理化处理。伪装Chrome版本匹配一个常见的、真实的Chrome版本号。处理Headless特征即使在无头模式下也会伪装出屏幕尺寸、用户代理等特征。但是仅靠Stealth插件是不够的。抖音这类大型平台的反爬系统是立体的还会检测行为模式。这就是为什么operator.js中的原子操作如此重要随机延迟在操作之间如点击之间、输入字符之间加入随机等待时间避免固定的、机器般的节奏。人类移动轨迹在点击元素前鼠标不是直线移动过去而是模拟一条带有随机控制点的贝塞尔曲线路径分多步移动到位。视口内滚动对于需要滚动才能看到的元素先平滑滚动到该元素进入视口再进行操作。关于与OpenClaw的复用文档中提到可以配置BROWSER_DEBUG_PORT18800来复用OpenClaw的浏览器实例。这是一个快速开始的捷径但我强烈不建议在生产环境或长期使用中这么做。因为OpenClaw自带的浏览器实例很可能没有启用Stealth插件其反检测能力是薄弱的。使用本项目自己启动的、集成了Stealth的浏览器实例是保证脚本不被平台轻易封禁的关键。4. 环境配置、部署与调试实战4.1 从零开始的本地环境搭建假设你是在一台全新的Linux或macOS开发机上部署以下是详细的步骤和避坑指南1. 获取项目与安装依赖git clone 项目仓库地址 cd douyin-upload-mcp-skill npm install这一步通常很顺利。如果遇到网络问题可以尝试配置npm镜像源。2. 关键配置调整.env文件项目根目录下的.env文件是配置核心。我建议首先复制一份.env.development用于本地调试cp .env .env.development然后重点修改.env.development中的以下几项BROWSER_HEADLESSfalse首次运行务必设为false。无头模式看不到界面你将无法扫码登录。首次成功登录并保存状态后后续可以尝试改为true以节省资源。BROWSER_PATH如果你系统上的Chrome不在标准路径或者你想用Edge就在这里指定完整路径如/usr/bin/google-chrome-stable或/Applications/Google Chrome.app/Contents/MacOS/Google Chrome。BROWSER_USER_DATA_DIR指定一个明确的路径如/home/yourname/douyin_browser_data。这便于你后期清理或备份登录数据。OUTPUT_DIR同样指定一个绝对路径确保有写入权限用于存放登录二维码等截图。3. 首次运行与登录不要直接运行Demo先通过MCP客户端配置来测试。以Claude Desktop为例找到其配置文件通常在~/Library/Application Support/Claude/claude_desktop_config.json添加MCP服务器配置{ mcpServers: { douyin_uploader: { command: node, args: [/ABSOLUTE/PATH/TO/douyin-upload-mcp-skill/src/mcp-server.js], env: { NODE_ENV: development } } } }保存并重启Claude Desktop。在聊天窗口你应该能看到新可用的工具。此时调用douyin_check_login工具。第一次调用它会打开浏览器因为你设置了非无头模式并返回二维码图片路径。去这个路径找到图片用抖音App扫码。扫码后迅速再次调用douyin_check_login。工具会检测到扫码成功并推进到下一步可能是直接登录成功也可能是短信验证。如果遇到短信验证就按照工具返回的phase提示继续调用并传入收到的验证码。首次登录成功的标志是工具返回phase: ‘logged_in’并且浏览器窗口停留在抖音创作者平台首页。这个过程可能需要手动调用工具3-4次。4.2 集成到AI工作流以Cursor为例让这个技能在Claude Desktop里工作只是第一步。更强大的用法是将其集成到像Cursor这样的AI编程IDE中实现“一句话发布内容”。Cursor同样支持MCP。你需要在Cursor的设置中例如通过Cursor: Open MCP Settings命令添加类似的服务器配置。配置成功后当你在Cursor的AI聊天框中描述需求时比如“写一个脚本遍历videos文件夹下的所有MP4文件并用合适的标题发布到抖音”Cursor的AI助手如Claude在思考过程中就能意识到它可以调用douyin_publish_video这个工具并为你生成相应的调用代码。一个进阶的集成思路是创建“复合工具”。例如你可以写一个本地的脚本这个脚本本身也通过MCP暴露为一个工具叫batch_publish_douyin。这个工具内部的工作流是1) 扫描目录2) 为每个视频用LLM生成标题和描述3) 循环调用douyin_publish_video。这样你在AI客户端只需要调用这一个复合工具就能触发一个复杂的批量处理流水线。4.3 调试技巧与问题排查实录自动化脚本出错是家常便饭。以下是几种常见的错误场景和我的排查思路问题一工具调用后无反应或超时检查Daemon进程首先确认Daemon是否在运行。可以ps aux | grep daemon查看或者直接访问http://localhost:40225默认端口看是否有响应。检查浏览器进程查看是否有Chrome进程在运行并且其启动参数中包含--remote-debugging-port40821或你配置的端口。查看日志在启动MCP Server或Demo时确保Node.js环境变量DEBUG*这样可以输出Puppeteer和项目内部的详细日志看到底卡在哪一步。问题二元素定位失败TimeoutError这是最常见的问题意味着脚本找不到它想点击或输入的元素。使用douyin_probe工具这是最有效的诊断工具。调用它它会返回当前页面的URL、标题以及一些关键元素如发布按钮、上传输入框是否存在。这能立刻告诉你页面是否处于预期状态。使用douyin_screenshot工具截图能让你直观地看到自动化浏览器当前看到的页面是什么样子。是不是登录页没跳转是不是出现了意外的弹窗如活动通知、升级提示截图一目了然。手动操作对比用相同的用户数据目录BROWSER_USER_DATA_DIR手动启动一个Chrome访问抖音创作者中心。观察页面结构是否与自动化脚本预期的一致。抖音的UI可能已更新导致选择器失效。问题三发布失败但无明确错误检查输出目录查看OUTPUT_DIR下是否有最新的截图。发布过程中的关键步骤如转码完成、发布点击后代码可能会截图这是宝贵的现场证据。检查网络和平台限制抖音对发布频率、视频格式、大小有严格限制。确保你的视频格式如MP4, H.264编码、尺寸比例如9:16竖屏符合要求并且当前账号没有因为频繁操作被临时限制。验证登录态再次调用douyin_check_login确认是否还处于logged_in状态。有时Cookies会意外失效。问题四被检测为自动化行为确保Stealth插件启用检查代码中puppeteer.launch的配置是否确实加载了stealthPlugin。增加行为随机性如果问题依旧可以尝试修改operator.js中模拟人类行为的参数比如增加操作之间的延迟范围让鼠标移动轨迹更“散漫”。考虑使用更稳定的IP部分检测可能与IP地址相关。使用家庭或办公室的固定宽带IP比数据中心机房的IP更可靠。5. 扩展思路与高级应用场景这个项目提供了一个强大的基础框架但它的潜力远不止于简单的上传。结合AI和自动化思维我们可以拓展出更多有趣的应用场景。场景一结合AIGC的内容创作流水线你可以构建一个端到端的流水线一个工具负责用GPT-4或Claude生成视频脚本。另一个工具调用文本转语音TTSAPI和图片/视频生成API如Sora、Runway将脚本变成带有配音和画面的短视频。最后调用douyin_publish_video并将上一步生成的视频路径和AI生成的标题/描述传入完成自动发布。 整个流程可以通过一个总控脚本或工作流引擎如n8n、Windmill串联起来实现“从一个想法到抖音发布”的全自动化。场景二数据驱动的分析与优化douyin_probe工具可以扩展。除了检查基本元素还可以让它解析页面数据比如抓取已发布视频的播放量、点赞、评论数据。分析创作者后台的粉丝增长趋势、热点话题。 将这些数据通过MCP反馈给AIAI就能进行分析并提出建议“你上周发布的骑行类视频平均播放量比美食类高50%建议本周多发布骑行内容”甚至可以自动调整后续的发布策略。场景三多账号管理与跨平台发布当前的架构设计Daemon 独立User Data Dir天然支持多账号。你可以为每个抖音账号配置一个独立的.env文件指定不同的BROWSER_USER_DATA_DIR。然后通过不同的MCP Server配置指向不同的入口脚本或使用不同环境变量来启动多个服务实例每个实例管理一个账号的浏览器会话。再结合一个调度系统就可以实现多账号的轮询发布、错峰发布最大化运营效率。更进一步你可以参考这个项目的模式为小红书、视频号、B站等平台开发类似的MCP技能。虽然各平台的前端操作不同但底层的CDP连接、Daemon管理、MCP协议封装都是可以复用的。最终你可以打造一个统一的“社交内容发布中台”让AI助手能够帮你管理全平台的账号和内容。这个项目的价值在于它成功地将一个复杂的、动态的Web交互过程标准化为AI世界里的一个稳定工具。它就像给AI装上了一双可以操控浏览器的手打开了无限的可能性。