vdl-mcp

vdl-mcp 通过模型上下文协议将 AI 助手连接到您自己的 vdl 服务器。真正的威力在于 Whisper 协同效应：

下载 → 转录 → 助手理解内容。

因此您可以这样说：

• "下载这个 YouTube 视频并总结它。"

• "抓取那个烹饪片段，把食谱列出来。"

• "这个采访中关于 X 说了什么？"

• "下载这个演讲的音频并给我关键点。"

工作原理

这是一个小型 stdio MCP 服务器，它与 vdl 的 REST API 通信，并使用您现有的 API 令牌进行身份验证。它本身不运行在 vdl 内部。

工具组是可切换的，并带有安全默认值：

禁用的组对助手不可见。

Related MCP server: popcorn

要求

• 一个正在运行的 vdl 实例。

• 一个 MCP 令牌：在 vdl 中打开 MCP 标签页 → 创建令牌并复制它。此令牌是有作用域的——它只能执行您在那里启用的 MCP 操作（写入/删除工具受切换开关和只读模式约束，其他操作在服务器端被拒绝），因此比通用 API 令牌更安全。

安装

使用 pipx（将 vdl-mcp 放入您的 PATH）：

pipx install git+https://github.com/sphings79/vdl-mcp

或使用 uv：

uv tool install git+https://github.com/sphings79/vdl-mcp

连接到 Claude Desktop

将此添加到您的 Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "vdl": {
      "command": "vdl-mcp",
      "env": {
        "VDL_URL": "http://localhost:8000",
        "VDL_TOKEN": "your-api-token"
      }
    }
  }
}

重启 Claude Desktop — vdl 工具就会出现。（任何支持 MCP 的客户端都以相同方式工作；只需通过 stdio 运行 vdl-mcp 命令。）

使用 Docker 运行

更喜欢容器？预构建镜像已发布到 GHCR — 将其用作命令：

{
  "mcpServers": {
    "vdl": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "VDL_URL", "-e", "VDL_TOKEN",
               "ghcr.io/sphings79/vdl-mcp:latest"],
      "env": {
        "VDL_URL": "http://host.docker.internal:8000",
        "VDL_TOKEN": "your-api-token"
      }
    }
  }
}

注意 -i（保持 stdin 打开以用于 stdio），并且当 vdl 运行在同一主机上时，使用 host.docker.internal 以便容器可以访问它。

无 Web UI — 设计如此

vdl-mcp 是一个由您的 MCP 客户端在本地启动的 stdio 进程。它不打开网络端口，因此没有登录页面，也没有 fail2ban — 没有入站流量需要保护。其安全模型是：保持您的 API 令牌私密，关闭破坏性工具（默认值），并可选择设置域名白名单。身份验证和暴力破解防护位于 vdl 本身。（如果您想要一个远程的多客户端 HTTP 服务器，那是不同的传输方式 — 请提交 issue。）

工具

• resolve(url) — 分析链接，列出项目和可用质量（不下载）。

• download(url, audio=False, section="", wait=True) — 下载最佳质量（或 MP3）；section 如 0:30-1:00 用于剪辑；wait 返回完成的文件 name。

• transcribe(name, language="") — Whisper 转录 → 返回文本（需要在 vdl 中设置 Whisper 模型）。

• get_transcript(name) — 返回现有转录的文本。

• list_files(query, service, label, limit) — 浏览您的下载。

• job_status(job_id) — 检查下载任务。

• （默认关闭） delete_file, bulk, get_settings。

配置（环境变量）

每个工具在其描述中都有标签 — [read]、[writes] 或 [deletes] — 以便您和助手都能一目了然地看到其风险。

也可以从 vdl 的 Web UI 进行管理： 在 vdl 中转到 设置 → MCP 标签页 以切换每个工具（带有只读主开关和风险标签）。vdl-mcp 在启动时获取该配置，因此无需环境变量 — 更改后重启 vdl-mcp。工具是否暴露的优先级顺序：只读（环境变量或 UI）→ 单个工具环境变量覆盖 → Web UI → 组标志。

安全说明

• 助手通过您的令牌以您的身份行动 — 请保持令牌私密。

• 破坏性工具默认关闭。 请有意识地启用它们。

• 根据助手的请求下载任意 URL 存在提示注入风险。设置 VDL_MCP_DOMAIN_ALLOWLIST（例如 youtube.com,instagram.com）以限制。

• 仅适用于您拥有或有权下载的内容 — 与 vdl 相同的免责声明。

许可证

GNU Affero General Public License v3.0（AGPL-3.0）— 参见 LICENSE。© 2026 sphings79