Skip to main content
Glama
ddbbiii

douyin-media-mcp

by ddbbiii
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Douyin Media MCP

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

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

目标工具

  • resolve_douyin_url：展开短链接并返回规范化页面地址、作品 ID 和基础元数据。

  • download_douyin_media：解析媒体流、下载、合并并返回本地文件与 manifest。

  • probe_media：检查时长、分辨率、帧率、编码、音轨和文件哈希。

Related MCP server: Wanyi Watermark Remover

已验证的解析链路

分享短链接
  -> 跟随重定向取得 /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 各自遵循其权利与许可证，本许可证不授予下载内容的再分发权。

Available Tools

3 tools
download_douyin_mediaA

Download, stream-copy mux, probe, decode-check, and hash authorized Douyin media.

If no independent audio stream is captured, a validated video-only file is returned with media_mode="video_only" and an explicit warning. Signed URLs are never exposed.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
qualityNobest
filenameNo
overwriteNo
output_dirYes
keep_separate_streamsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description adds important behavioral details: handling of missing audio stream (video-only fallback) and security note about signed URLs. This compensates well for the absence of annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus a bullet point; compact and front-loaded with the core action. However, the list of operations (stream-copy, mux, etc.) is somewhat dense and could be reorganized for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists (not shown) but the description references a return field (media_mode) and warning, which helps. However, with 6 parameters and no explanations, the description is insufficient for full understanding of the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description does not explain any of the 6 parameters (e.g., quality, filename, overwrite). The only indirectly related info is about audio stream handling, which does not clarify parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: download Douyin media, and lists specific operations (stream-copy mux, probe, decode-check, hash). It distinguishes from siblings which are URL resolution and probing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use vs alternatives; however, sibling tools have distinct purposes (resolve URL, probe media), making usage somewhat implied. No exclusions or preconditions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

probe_mediaC

Inspect a local media file with FFprobe, SHA-256, and optional three-point decoding.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
decode_checkNo
require_audioNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. It discloses the inspection nature and tools used, but lacks details on side effects (e.g., whether it modifies the file), required permissions, or what 'three-point decoding' entails. The behavioral disclosure is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, but it is under-specified. Front-loading is adequate but the brevity comes at the cost of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters and an output schema, the description provides only a high-level summary. It does not mention return values (though output schema may cover this), prerequisites, or the meaning of the decode check option. The lack of context makes it insufficient for confident use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 3 parameters with 0% description coverage; the description does not explain any parameter beyond implicit reference to 'optional three-point decoding' (possibly relating to decode_check). It adds no meaningful context about path, decode_check, or require_audio beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it inspects a local media file using specific tools (FFprobe, SHA-256) and optional decode check, clearly identifying the verb and resource. It does not explicitly differentiate from siblings but the sibling tools (Douyin-related) are in a different domain, so purpose is clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives or any prerequisites. The description only states what it does without context on use cases or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_douyin_urlA

Resolve a Douyin share URL without saving media or exposing signed stream URLs.

Use browser_mode="auto" normally. "direct" only expands redirects; "browser" forces Playwright network observation. Human verification challenges are reported, never bypassed.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
browser_modeNoauto

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries behavioral disclosure. It explicitly states limitations: does not save media, does not expose signed stream URLs, and challenges are reported but not bypassed. This is transparent, though it could mention if any authentication or rate limits apply.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences no wasted words. The first sentence states purpose and constraints, the second explains modes. It is front-loaded with the most critical information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, return values need not be described. The description covers purpose, behavior, and mode guidance. It might be missing potential error scenarios or prerequisites, but overall it is sufficiently complete for a URL resolution tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. The description explains the url parameter implicitly (the share URL) and thoroughly describes browser_mode options ('auto', 'direct', 'browser') with their behaviors, adding meaning beyond the schema's defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool resolves a Douyin share URL without saving media or exposing signed stream URLs. It uses a specific verb ('resolve') and resource ('Douyin share URL'), and distinguishes from siblings like download_douyin_media (saves media) and probe_media (likely probes, not resolves).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on using browser_mode: 'auto' normally, 'direct' for redirect expansion, 'browser' for Playwright observation. It mentions human verification challenges are reported but not bypassed, implying when not to expect full resolution. However, it does not explicitly state when to use alternative tools like download_douyin_media.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: resolving URLs, downloading media, and probing local files. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: resolve_douyin_url, download_douyin_media, probe_media. Naming is uniform and predictable.

Tool Count5/5

With only 3 tools, the server is tightly scoped to the Douyin media domain. Each tool serves a necessary function without redundancy.

Completeness4/5

The set covers the core workflow: resolving, downloading, and probing. Missing a tool for fetching metadata from a URL without downloading might be a minor gap, but overall complete for its purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ddbbiii/douyin-media-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server