AI导哈

YouTube字幕提取服务

一个用于提取YouTube视频字幕的Rust服务，支持多种输出格式并与MCP客户端兼容。

  • by Alatar86
  • Rust
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 Alatar86/ironbeard-mcp-youtube

使用说明

铁胡子mcp youtube

用于提取YouTube视频转录的MCP服务器。单一Rust二进制文件。不需要Python、Node或yt-dlp。

特征

  • 从任何有字幕的YouTube视频中抓取文字记录
  • 四种输出格式：纯文本、带时间戳、SRT字幕、JSON
  • 具有前缀匹配和自动回退功能的语言解析
  • 基于文件的缓存，具有7天TTL（SHA-256哈希密钥）
  • 网络错误指数回退的重试
  • 使用YAML frontmatter将成绩单保存为markdown
  • 适用于Linux、macOS和Windows
  • 插入Claude Desktop、Cursor或任何MCP客户端

安装

git clone https://github.com/Alatar86/ironbeard-mcp-youtube.git
cd ironbeard-mcp-youtube
cargo build --release

Binary登陆 target/release/ironbeard-mcp-youtube.

用法

MCP服务器设置

服务器通过stdio运行。将MCP客户端指向二进制文件。

克劳德桌面版 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/ironbeard-mcp-youtube"
    }
  }
}

光标 (.cursor/mcp.json 在工作区根目录中）：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/ironbeard-mcp-youtube"
    }
  }
}

工具： get_youtube_transcript

参数 类型 必填 说明
url string 是 YouTube视频URL或11个字符的视频ID
language string 否 BCP-47语言代码（例如。， en, es, ja).默认为视频的主要语言。
format string 否 输出格式： plain （默认）， timestamped, srt, json

接受的URL格式：

  • https://www.youtube.com/watch?v=VIDEO_ID
  • https://youtu.be/VIDEO_ID
  • https://youtube.com/embed/VIDEO_ID
  • 原始11个字符的视频ID（例如。， dQw4w9WgXcQ)

命令行选项

标志 描述 默认值
--transcript-dir <PATH> 在哪里保存成绩单 .md 文件 ~/Documents/youtube-transcripts
--cache-dir <PATH> 在哪里存储缓存的转录JSON 平台缓存目录（见下文）

作为Rust库

use ironbeard_mcp_youtube::{TranscriptService, OutputFormat, SaveOutcome};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let service = TranscriptService::new()?;

    let result = service
        .get_transcript("dQw4w9WgXcQ", Some("en"), OutputFormat::Plain)
        .await?;

    println!("{}", result.formatted_text);
    match &result.save_outcome {
        SaveOutcome::Saved(path) => println!("Saved to: {}", path.display()),
        SaveOutcome::Failed(err) => eprintln!("Save failed: {}", err),
        SaveOutcome::NotAttempted => {}
    }
    Ok(())
}

输出格式

平原

所有用空格连接的标题文本：

We're no strangers to love You know the rules and so do I...

时间戳

每段前缀为 [HH:MM:SS]:

[00:00:18] We're no strangers to love
[00:00:22] You know the rules and so do I

字幕

标准字幕格式：

1
00:00:18,000 --> 00:00:22,000
We're no strangers to love

2
00:00:22,000 --> 00:00:27,000
You know the rules and so do I

JSON

结构化数组：

[
  {"start": 18.0, "duration": 4.0, "text": "We're no strangers to love"},
  {"start": 22.0, "duration": 5.0, "text": "You know the rules and so do I"}
]

保存的成绩单

每个成绩单都保存为一个名为的markdown文件 {title} - {author}.md 使用YAML frontmatter：

---
title: "Never Gonna Give You Up"
author: "Rick Astley"
video_id: "dQw4w9WgXcQ"
url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
language: "en"
duration: "00:03:33"
duration_seconds: 213
date_saved: "2026-02-17"
---

# Never Gonna Give You Up

We're no strangers to love You know the rules and so do I...

配置

环境变量 描述 默认值
TRANSCRIPT_DIR 在哪里 .md 转录文件已保存 ~/Documents/youtube-transcripts
YT_CLIENT_VERSION Android YouTube应用程序版本发送到innertube API。当YouTube弃用内置版本时进行覆盖（请参阅 故障排除) 21.02.35

您可以在MCP客户端配置中进行设置：

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/ironbeard-mcp-youtube",
      "env": {
        "TRANSCRIPT_DIR": "/path/to/my/transcripts"
      }
    }
  }
}

这 --transcript-dir CLI标志优先于环境变量。

缓存

转录作为JSON文件缓存在平台缓存目录中：

平台 目录
Linux ~/.cache/ironbeard-mcp-youtube/
macOS ~/Library/Caches/ironbeard-mcp-youtube/
窗户 %LOCALAPPDATA%\ironbeard-mcp-youtube\

缓存密钥是SHA-256哈希值 video_id + language。参赛作品将在7天后过期，并在访问时进行清理。

运作原理

  1. 从URL或原始ID解析视频ID
  2. 检查文件缓存中的有效条目
  3. 在错过时，点击YouTube的内胎 /player 用于元数据和字幕轨道URL的API
  4. 从解析的字幕轨道中获取timedtext XML
  5. 将XML解析为转录行，解码HTML实体
  6. 将结果缓存为JSON
  7. 使用YAML frontmatter将成绩单另存为markdown
  8. 以请求的输出格式格式化并返回成绩单

语言解析首先尝试精确匹配，然后尝试前缀匹配(en 比赛 en-US)，然后回落到第一个可用曲目。网络请求最多重试3次，采用指数回退（1s、2s、4s）。

建筑学

src/
  main.rs           - Entry point, CLI args, starts MCP server on stdio
  lib.rs            - Public API exports
  server.rs         - MCP server (rmcp 0.15), tool definitions
  service.rs        - TranscriptService: fetch, cache, format, save
  config.rs         - Configuration (directories, env vars, defaults)
  youtube/
    mod.rs          - Video ID parsing, module exports
    api.rs          - Transcript fetching with retry logic
    client.rs       - HTTP client with cookie/consent handling
    parser.rs       - Player API JSON, timedtext XML, and json3 parsing
    proto.rs        - Manual protobuf encoding for innertube params
    types.rs        - Data structures (TranscriptLine, VideoMetadata, etc.)
    error.rs        - Error types (VideoNotFound, NoCaptions, RateLimited, etc.)
  processing/
    mod.rs          - Output formatters (plain, timestamped, SRT, JSON)
  cache/
    mod.rs          - File-based transcript cache with SHA-256 keys and TTL
tests/
  integration_test.rs - End-to-end tests against live YouTube

依赖项

板条箱 用途
rmcp MCP服务器框架（stdio传输）
tokio 异步运行时
reqwest 支持cookie的HTTP客户端
serde / serde_json 序列化
schemars MCP工具输入的JSON模式生成
regex URL解析、XML提取
sha2 缓存密钥哈希
dirs 特定于平台的目录解析
clap CLI参数解析
chrono 封面的日期格式
anyhow 应用程序错误处理
thiserror 错误类型推导
tracing / tracing-subscriber 结构化日志记录
base64 / urlencoding 用于内胎API的Protobuf参数编码
slug 非拉丁标题的文件名屏蔽
lazy_static 静态正则表达式编译

发展

# Unit tests (offline)
cargo test --lib

# All tests including integration (hits YouTube)
cargo test

# Check formatting
cargo fmt --check

# Lint
cargo clippy

# Build release
cargo build --release

故障排除

每次获取失败，返回“播放器API返回HTTP 400”

YouTube定期弃用旧的Android应用程序版本和请求 模拟已弃用的版本会被HTTP 400拒绝 （“先决条件检查失败”）。如果每个视频突然都以这种方式失败 内置客户端版本可能已被弃用。

通过设置修复它，而无需重新编译 YT_CLIENT_VERSION 到电流 安卓应用程序版本-yt-dlp跟踪一个 INNERTUBE_CLIENTS['android']:

{
  "mcpServers": {
    "youtube-transcript": {
      "command": "/path/to/ironbeard-mcp-youtube",
      "env": {
        "YT_CLIENT_VERSION": "21.02.35"
      }
    }
  }
}

局限性

  • 视频需要字幕（人工或自动生成）
  • 视频必须公开
  • 语言可用性取决于YouTube的内容
  • 快速请求可能会受到速率限制（服务器会自动重试）

许可证

麻省理工学院

联系

Bug报告： GitHub问题 或Ironbeardai@gmail.com

相关 MCP