Douyin Media MCP

一个面向本地自动化的轻量 MCP 服务：接收用户提供的抖音分享链接，解析页面中的临时媒体流，将视频流和可选音频流下载到本地，使用 FFmpeg 无损封装，并用 FFprobe 验收结果。

项目只做“链接解析与媒体落盘”，不包含视频笔记 UI、AI 总结、转写、数据库或内容管理系统。

目标工具

• resolve_douyin_url：展开短链接并返回规范化页面地址、作品 ID 和基础元数据。
• download_douyin_media：解析媒体流、下载、合并并返回本地文件与 manifest。
• probe_media：检查时长、分辨率、帧率、编码、音轨和文件哈希。

已验证的解析链路

分享短链接
  -> 跟随重定向取得 /video/<aweme_id>
  -> 浏览器加载真实作品页
  -> 监听/枚举页面媒体请求
  -> 识别 video_mp4 视频流，并尽力识别独立音频流
  -> 携带页面 Referer、User-Agent（必要时 Cookie）下载临时签名 URL
  -> FFmpeg stream copy 合并
  -> FFprobe + SHA-256 验收
  -> 写入不含 Cookie/临时签名 URL 的 manifest

2026-07-19 已在 Windows 上完成两层真实验证：浏览器辅助基线取得 1920×1080 H.264 + AAC 完整媒体；独立 MCP Playwright 流程取得 1280×720 H.264 无声视频，时长约 21 分 50 秒，并通过三点解码与 SHA-256 验收。验证细节见 docs/VERIFIED_PIPELINE.md。

设计原则

• 浏览器解析是正式 fallback，不依赖页面 HTML 中存在固定直链。
• 临时签名 URL、Cookie 和浏览器凭据不得写入日志、manifest 或 Git。
• 下载完成后才返回成功；必须验证视频流、时长和可解码性。有音频时同时验证音轨；没有捕获音频时返回 media_mode=video_only 和明确警告。
• 支持后台下载和有界并发，但解析阶段默认低并发，避免触发平台风控。
• 不绕过 DRM、验证码、付费墙或权限控制，不提供去水印功能。
• 只处理用户有权访问和保存的内容，并遵守平台条款与适用法律。

安装

需要 Python 3.11+、Chrome/Chromium、FFmpeg 和 FFprobe。推荐使用 uv：

git clone <repository-url>
cd douyin-media-mcp
uv sync --extra dev
uv run douyin-media-mcp

如果系统没有 Chrome，可安装 Playwright 自带 Chromium：

uv run playwright install chromium

MCP 客户端配置

Codex 的 config.toml 示例：

[mcp_servers.douyin-media]
command = "uv"
args = ["--directory", "<repository-path>", "run", "douyin-media-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 1800

Claude Code：

claude mcp add douyin-media -- uv --directory <repository-path> run douyin-media-mcp

Claude Desktop 可使用等价的 stdio 配置：

{
  "mcpServers": {
    "douyin-media": {
      "command": "uv",
      "args": ["--directory", "<repository-path>", "run", "douyin-media-mcp"]
    }
  }
}

KeyHub 本机配置

项目包含 .keyhub.json，可以扫描或添加到 KeyHub Project Desk。KeyHub 只管理本机浏览器模式、CDP 附着和是否临时使用 Cookie 等可选运行参数；它不会保存或导出浏览器 Cookie、下载结果或临时签名地址。

这是 stdio MCP，不应在 KeyHub 中孤立常驻启动。应由 Codex、Claude Code 或 Claude Desktop 启动；将它们的 MCP 启动命令包在 keyhub run --project douyin-media-mcp -- ... 中，即可在每次启动时从 KeyHub 注入已绑定的项目环境变量。具体注册、开关和客户端包装配置见 docs/KEYHUB.md。

浏览器模式

默认启动本机 Chrome 的独立临时上下文并显示浏览器窗口。可通过环境变量调整：

• DOUYIN_MCP_BROWSER_HEADLESS=1：使用无头模式；更容易触发平台风控，不推荐作为默认值。
• DOUYIN_MCP_BROWSER_PROFILE=<path>：使用由用户管理的持久化 profile。目录不会被复制或提交。
• DOUYIN_MCP_CDP_URL=http://127.0.0.1:9222：附着到用户已启动的 Chromium。
• DOUYIN_MCP_USE_BROWSER_COOKIES=1：仅在用户明确允许时，把当前上下文 Cookie 临时用于媒体请求；Cookie 不落盘到 manifest 或日志。
• DOUYIN_MCP_BROWSER_CHANNEL=：留空后使用 Playwright 自带 Chromium；默认使用系统 Chrome。

工具行为

• resolve_douyin_url 的公共结果只包含作品地址、ID、元数据和候选数量，不包含签名媒体 URL。
• download_douyin_media 只在下载、无损封装、FFprobe、三点解码和 SHA-256 全部通过后返回成功；独立音频流是可选项。请求的清晰度是选择上限，实际分辨率以当次页面候选和返回字段为准。
• probe_media 可单独验证任意本地媒体文件；仅在调用方设置 require_audio=true 时把缺少音轨视为失败。
• 遇到登录、验证码或访问限制时返回结构化错误，不自动绕过。

当前状态

首个 MCP 实现已经完成。浏览器只能捕获视频流时会保存经过验收的无声视频，不再阻断任务。已验证的长视频基线和仍待补充的测试矩阵见 docs/VERIFIED_PIPELINE.md 与 docs/MAINTAINER_BACKLOG.md。单条链接成功不代表任意抖音内容都长期可用。

许可证

MIT。第三方网站内容、浏览器组件和 FFmpeg 各自遵循其权利与许可证，本许可证不授予下载内容的再分发权。