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格式：

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

命令行选项

作为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...

配置

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

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

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

缓存

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

缓存密钥是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

依赖项

发展

# 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

局限性

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

许可证

麻省理工学院

联系

Bug报告： 或Ironbeardai@gmail.com