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。

Related MCP server: Wanyi Watermark Remover

能力

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

1. douyin_transcribe_link_accurate：提交公开抖音链接，创建本机 Qwen 转写任务。

2. douyin_get_accurate_transcription_job：查询后台任务状态。

3. douyin_read_transcript：按片段读取长字幕。

4. douyin_search_transcript：在字幕中搜索关键词和时间点。

5. 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

1. 在 OpenAI Platform Tunnel 设置 创建 Tunnel。

2. 创建专用的 runtime API key。不要把 key 发到聊天、Issue、截图或日志中。

3. 双击 CONFIGURE_TUNNEL.cmd。

4. 按提示粘贴自己的 tunnel_id；输入 API key 时终端不会显示字符。

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

6. 启动并连接 ChatGPT

1. 双击 START.cmd。

2. 双击 STATUS.cmd，确认 localMcpReady、tunnelHealthy、tunnelReady 都为 true。

3. 在 ChatGPT 打开 Developer Mode。

4. 进入插件页面，点击加号，Connection 选择 Tunnel。

5. 选择刚才创建的 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。