Douyin Claw MCP

一个面向本机运行的抖音 MCP 服务。它把 DouYin_Spider 的采集能力封装成 MCP 工具，并提供本地网页控制台，用于查看运行状态、抓取结果、评论、直播事件和私信监听状态。

项目当前以 Windows 为主要使用环境，推荐通过 start_mcp.bat 启动。MCP 使用 stdio 传输，不需要把服务暴露到公网。

功能

• 登录管理：扫码登录、登录会话状态查询、认证状态查询、退出登录

• 内容采集：视频/图集详情、用户信息、用户作品、视频搜索、用户搜索、直播间搜索

• 互动数据：评论及回复、收藏列表、推荐流

• 文件能力：下载视频/图集，截取视频指定时间点的画面

• 直播能力：查询直播间信息，启动/轮询/停止直播事件监听

• 私信能力：启动/轮询/停止私信监听

• 账号操作：点赞、收藏、发表评论、发送直播消息、发送私信

• 本地控制台：展示运行状态、工具调用、统计数据和已保存结果

搜索视频和获取评论对相同请求提供 5 分钟进程内缓存；结果和统计会写入本地文件，控制台可以持续读取这些数据。涉及点赞、收藏、评论和消息发送的工具要求显式传入 confirm=true。

Related MCP server: Douyin API New MCP Server

环境要求

• Windows

• Python 3.10+（建议使用 Python 3.12）

• 网络连接和一个已登录的抖音账号

• Playwright Chromium；安装脚本会自动安装

Node.js 18+ 仅在需要构建 DouYin_Spider 的 Electron 桌面版时使用，运行 MCP 本身不要求 Node.js。

安装

最简单的方式是在项目目录双击：

install.bat

安装脚本会创建 .venv，安装根目录 requirements.txt，并安装 Playwright Chromium。也可以手动执行：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m playwright install chromium

启动 MCP 和控制台

推荐双击：

start_mcp.bat

脚本会选择可用的 Python 并启动 MCP。MCP 客户端实际调用工具后，控制台会自动记录调用状态和结果。控制台地址为：

http://127.0.0.1:8765/

如果只需要启动网页控制台，可双击 start_dashboard.bat，然后在控制台中启动 MCP。也可以直接运行：

.\.venv\Scripts\python.exe .\mcp_server.py

如果项目移动到了其他位置，请同步修改 mcp_config.example.json 和 workbuddy_mcp.example.json 中的绝对路径。

配置 MCP 客户端

复制并修改 mcp_config.example.json，把其中的 D:\\Desktop\\douyin_claw 替换为实际项目路径，再将 mcpServers.douyin-spider 添加到 MCP 客户端配置中。

示例配置使用 Windows 的 cmd.exe 调用 start_mcp.bat，并将统计文件固定到项目的 work/mcp_stats.json。服务默认使用 stdio，不要把它改成公网 HTTP 服务。

首次登录

启动 MCP 后，在 MCP 客户端依次调用：

1. douyin_login：打开可见浏览器，扫码或完成登录。

2. douyin_login_status：查询本次登录会话是否完成。

3. douyin_auth_status：确认普通抖音和直播登录状态。

登录信息保存在本机 DouYin_Spider/.env 中。Cookie 不会作为工具结果返回，也不应提交到 Git 或发送给其他人。退出登录可调用 douyin_logout。

工具速查

监听采用“启动 / 轮询 / 停止”模式，避免单个 MCP 调用长期阻塞。capture_video_frame 适合接在 search_videos 后使用；capture_work_frame 则直接接收作品链接。截图需要 FFmpeg，程序会优先查找项目内 .browser 的随包版本，也可以通过 FFMPEG_PATH 指定本机 FFmpeg。

项目结构

.
├── mcp_server.py                  # MCP stdio 服务和工具定义
├── mcp_auth.py                    # 本地扫码登录及 Cookie 管理
├── mcp_stats.py                   # 统计、日志和结果记录
├── dashboard_server.py            # 本地网页控制台服务
├── dashboard.html                 # 控制台页面
├── live_monitor.py                # 直播事件监听适配
├── private_monitor.py             # 私信 WebSocket 监听适配
├── install.bat                    # 安装依赖
├── start_mcp.bat                  # 启动 MCP
├── start_dashboard.bat            # 只启动控制台
├── mcp_config.example.json         # MCP 客户端配置示例
└── DouYin_Spider/                 # 原始抖音 API、签名、直播和 Electron 代码

运行时数据默认位于 work/、outputs/ 和 DouYin_Spider/datas/，这些目录已加入 .gitignore。

Electron 桌面版（可选）

DouYin_Spider 内含 Electron 桌面端代码。需要 Node.js 18+ 时，在该目录执行：

cd .\DouYin_Spider
npm install
npm start

构建 Windows 安装包：

npm run dist

安装包会输出到 DouYin_Spider/release/，该目录不纳入版本控制。

安全与合规

• 仅在本机使用，建议保持 stdio 传输，不要暴露公网端口。

• 仅使用本人账号或已获授权的数据，并遵守抖音平台规则及适用法律。

• 不要提交 .env、Cookie、登录文件、运行结果或下载的媒体文件。

• 抓取和互动接口可能受抖音页面、接口和风控策略变化影响；遇到失败时请先确认登录状态和网络环境。

致谢

采集核心代码位于 DouYin_Spider，其原始项目说明和许可证信息请参阅该目录下的 README.md 与 package.json。