ironbeard-mcp-youtube

MCP server for pulling YouTube video transcripts. Single Rust binary. No Python, Node, or yt-dlp needed.

Features

• Grabs transcripts from any YouTube video that has captions
• Four output formats: plain text, timestamped, SRT subtitles, JSON
• Language resolution with prefix matching and automatic fallback
• File-based caching with 7-day TTL (SHA-256 hashed keys)
• Retries with exponential backoff on network errors
• Saves transcripts as markdown with YAML frontmatter
• Works on Linux, macOS, and Windows
• Plugs into Claude Desktop, Cursor, or any MCP client

Installation

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

Binary lands at target/release/ironbeard-mcp-youtube.

Usage

MCP Server Setup

The server runs over stdio. Point your MCP client at the binary.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Cursor (.cursor/mcp.json in workspace root):

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

Tool: get_youtube_transcript

Parameter	Type	Required	Description
url	string	Yes	YouTube video URL or 11-character video ID
language	string	No	BCP-47 language code (e.g., en, es, ja). Defaults to the video's primary language.
format	string	No	Output format: plain (default), timestamped, srt, json

Accepted URL formats:

• https://www.youtube.com/watch?v=VIDEO_ID
• https://youtu.be/VIDEO_ID
• https://youtube.com/embed/VIDEO_ID
• Raw 11-character video ID (e.g., dQw4w9WgXcQ)

Command-Line Options

Flag	Description	Default
--transcript-dir <PATH>	Where to save transcript .md files	~/Documents/youtube-transcripts
--cache-dir <PATH>	Where to store cached transcript JSON	Platform cache directory (see below)

As a Rust Library

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(())
}

Output Formats

Plain

All caption text joined with spaces:

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

Timestamped

Each segment prefixed with [HH:MM:SS]:

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

SRT

Standard SubRip subtitle format:

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

Structured array:

[
  {"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"}
]

Saved Transcripts

Every transcript gets saved as a markdown file named {title} - {author}.md with 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...

Configuration

Environment Variable	Description	Default
TRANSCRIPT_DIR	Where .md transcript files get saved	~/Documents/youtube-transcripts

You can set this in your MCP client config:

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

The --transcript-dir CLI flag takes precedence over the environment variable.

Cache

Transcripts are cached as JSON files in the platform cache directory:

Platform	Directory
Linux	~/.cache/ironbeard-mcp-youtube/
macOS	~/Library/Caches/ironbeard-mcp-youtube/
Windows	%LOCALAPPDATA%\ironbeard-mcp-youtube\

Cache keys are SHA-256 hashes of video_id + language. Entries expire after 7 days and get cleaned up on access.

How It Works

1. Parse the video ID from the URL or raw ID
2. Check the file cache for a valid entry
3. On miss, hit YouTube's innertube /player API for metadata and caption track URLs
4. Fetch the timedtext XML from the resolved caption track
5. Parse the XML into transcript lines, decode HTML entities
6. Cache the result as JSON
7. Save transcript as markdown with YAML frontmatter
8. Format and return the transcript in the requested output format

Language resolution tries exact match first, then prefix match (en matches en-US), then falls back to the first available track. Network requests retry up to 3 times with exponential backoff (1s, 2s, 4s).

Architecture

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

Dependencies

Crate	Purpose
rmcp	MCP server framework (stdio transport)
tokio	Async runtime
reqwest	HTTP client with cookie support
serde / serde_json	Serialization
schemars	JSON Schema generation for MCP tool input
regex	URL parsing, XML extraction
sha2	Cache key hashing
dirs	Platform-specific directory resolution
clap	CLI argument parsing
chrono	Date formatting for frontmatter
anyhow	Application error handling
thiserror	Error type derivation
tracing / tracing-subscriber	Structured logging
base64 / urlencoding	Protobuf param encoding for innertube API
slug	Filename slugification for non-Latin titles
lazy_static	Static regex compilation

Development

# 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

Limitations

• Video needs captions (human or auto-generated)
• Video must be public
• Language availability depends on what YouTube has
• Rapid requests can get rate-limited (server retries automatically)

License

MIT

Contact

Bug reports: GitHub Issues or Ironbeardai@gmail.com