MCP 服务器

douyin-transcript-mcp

Enables transcribing public Douyin videos to text using a local AI model, providing read-only tools for transcription, search, and listing.

README

Douyin Transcript MCP

一个独立、只读、本机优先的抖音语音转文字 MCP。把公开抖音视频链接交给 ChatGPT 或其他 MCP 客户端，视频会在你自己的 Windows 电脑上下载并由 Qwen3-ASR-1.7B 转录；字幕、模型和运行凭据都留在本机。

English

为什么不需要 VPS

推荐架构只有三层：

ChatGPT / Codex
      │ OpenAI Secure MCP Tunnel（仅出站 HTTPS 443）
      ▼
你的 Windows 电脑：Douyin Transcript MCP
      │
      └─ Qwen3-ASR + 本地字幕缓存

不开放公网入站端口。
不使用 VPS、反向 SSH、Cloudflare Quick Tunnel 或固定公网 URL。
电脑重启后再次运行 START.cmd，原来的 tunnel identity 不变，ChatGPT 中无需换 URL。
电脑必须开机并联网，插件才能调用本机模型。

这里的“分发”是指公开 GitHub 源码，让每位用户在自己的电脑上运行并创建自己的私有 Tunnel。OpenAI 官方说明 Secure MCP Tunnel 适合私有服务器和开发模式，但不能替代公开插件提交所要求的稳定公网 HTTPS 服务。参见 Secure MCP Tunnel 与连接 ChatGPT。

能力

仓库只暴露五个只读工具：

douyin_transcribe_link_accurate：提交公开抖音链接，创建本机 Qwen 转写任务。
douyin_get_accurate_transcription_job：查询后台任务状态。
douyin_read_transcript：按片段读取长字幕。
douyin_search_transcript：在字幕中搜索关键词和时间点。
douyin_list_transcripts：列出本机缓存。

它只处理视频语音，不识别纯画面、贴纸或画面文字；字幕属于不可信外部内容，不能当作指令执行。

适用环境

Windows 10/11 x64
Node.js 20 或更高版本
Python 3.12（也可由 uv 管理）
NVIDIA GPU，建议至少 8 GB 显存
至少 12 GB 可用磁盘空间
FFmpeg 与 FFprobe 已加入 PATH
能够访问抖音、ModelScope、GitHub 和 OpenAI 的出站 HTTPS
OpenAI Platform Tunnel 权限与 ChatGPT Developer Mode；具体可用性取决于账号和工作区策略

安装

1. 准备基础软件

安装 Node.js 20+、Python 3.12/uv 和 FFmpeg。Windows 可通过 winget 安装 FFmpeg：

winget install --id Gyan.FFmpeg -e

重新打开终端后确认：

node --version
ffmpeg -version
ffprobe -version

2. 构建 MCP

双击 SETUP.cmd。它会运行 npm ci、类型检查、构建和离线 fixtures。

3. 安装本机 Qwen3-ASR

双击 INSTALL_QWEN.cmd。安装器会：

创建隔离的 Python 环境；
安装并校验 CUDA 版 PyTorch；
安装 Qwen3-ASR 与 ModelScope；
下载 Qwen3-ASR-1.7B 到被 Git 忽略的 runtime/。

模型较大，只需下载一次。

4. 安装 OpenAI 官方 tunnel-client

双击 INSTALL_TUNNEL_CLIENT.cmd。脚本只从 OpenAI 官方 GitHub Release 的 latest 版本下载 Windows x64 资产，并根据 Release 提供的 SHA-256 摘要校验；二进制保存在被 Git 忽略的 tools/。

5. 创建并配置自己的 Tunnel

在 OpenAI Platform Tunnel 设置创建 Tunnel。
创建专用的 runtime API key。不要把 key 发到聊天、Issue、截图或日志中。
双击 CONFIGURE_TUNNEL.cmd。
按提示粘贴自己的 tunnel_id；输入 API key 时终端不会显示字符。

API key 使用 Windows DPAPI CurrentUser 加密，配置和 tunnel profile 只写入被忽略且限制 ACL 的 runtime/private-config/。它不能跨 Windows 用户或跨电脑直接恢复；换电脑时应重新创建配置。

6. 启动并连接 ChatGPT

双击 START.cmd。
双击 STATUS.cmd，确认 localMcpReady、tunnelHealthy、tunnelReady 都为 true。
在 ChatGPT 打开 Developer Mode。
进入插件页面，点击加号，Connection 选择 Tunnel。
选择刚才创建的 Tunnel，确认发现的工具恰好是上面的五个只读工具。

现在可以直接说：“请用抖音转文字处理这个链接：……”

交给 AI 部署和排查

如果不熟悉终端，不需要自己猜命令。把仓库链接交给能够操作本机的 AI 编程助手，让它完整阅读 AI_SETUP.md。该文档已经写明：

从环境检查、安装 Qwen、配置 Tunnel 到真实 ChatGPT 验收的完整顺序；
DIAGNOSE.cmd 每个布尔字段的含义和下一步；
Windows 重启、Tunnel 未就绪、工具不可见、链接解析失败和转录失败的分层排查方法，详见 TROUBLESHOOTING.md；
哪些步骤必须由设备所有者本人输入敏感信息；
哪些结果只是静态检查，哪些才算真实端到端可用。

AI 编程工具还可以自动读取 AGENTS.md 中的项目边界。需要求助前请先阅读 SUPPORT.md：这是自助式实验项目，优先由使用者自己的 AI 按文档检查和修复，不提供逐台电脑的远程安装或个人环境人工兜底。

日常使用

每次 Windows 重启后运行 START.cmd。
查看状态运行 STATUS.cmd。
安全停止运行 STOP.cmd；模型和字幕缓存不会删除。
排查环境运行 DIAGNOSE.cmd；它只输出布尔状态，不输出 key 或 tunnel ID。

备份

可备份 runtime/transcripts/ 中已经完成的字幕。模型和 Python 环境可以重新下载，不建议备份。不要把以下内容上传 GitHub、网盘公开链接或 Issue：

runtime/private-config/
runtime/tunnel-*、runtime/pids.json
logs/
tools/
Qwen 模型、Python 虚拟环境和下载缓存

开发验证

npm ci
npm test
npm run start:http

HTTP 调试端点只监听 127.0.0.1:31338/mcp，不会监听局域网或公网地址。也可以运行 npm run start:stdio 连接其他本地 MCP 客户端。

安全与边界

只接受不含账号信息、自定义端口的抖音 HTTPS 链接。
每一次跳转都执行 DNS 和私网/保留地址检查，避免 SSRF。
媒体下载有大小、超时和类型限制，临时文件在任务结束后清理。
子进程不会继承名称中含 token、secret、password、cookie 或 authorization 的环境变量。
日志会删去媒体路径、查询参数和常见令牌格式。
工具均为只读，不负责登录、点赞、评论、发布、删除或绕过访问控制。

完整说明见 SECURITY.md。

项目来源与许可

此仓库从 douyin-controlled-mcp 中经过白名单抽取，移除了浏览器控制、账号操作、VPS 中继、Cloudflare 和写入工具，形成独立的本机转录项目。项目代码使用 MIT License；依赖与模型遵循各自许可证，见 THIRD_PARTY_NOTICES.md 和 PROJECT_ORIGIN.md。