yt-media-info MCP

Extract rich metadata, transcripts, and search from any yt-dlp-supported media URL — for Claude, Anthropic, and any MCP-compatible AI assistant.

yt-media-info MCP is a Model Context Protocol (MCP) server that lets AI assistants extract structured metadata from media URLs across 1800+ sites using yt-dlp — YouTube, Vimeo, Twitch, podcasts, and more. Given a URL (video, playlist, channel, podcast), it returns title, description, duration, chapters, subtitles/captions, formats, and statistics that models can reason over.

Built to sit alongside web-search tools as a media-enrichment step in an information-gathering pipeline. Works with Claude Desktop, Claude Code, LiteLLM, and any MCP client over stdio or SSE.

Works with

Compatible with any client that speaks the Model Context Protocol:

• Claude Desktop — via stdio transport

• Claude Code — via SSE transport

• LiteLLM — as an mcp model in the gateway config

• Open WebUI and any MCP-aware agent framework

• Custom apps — via the MCP SDK (SSE) or the plain JSON POST /api shortcut

Related MCP server: YouTube Content Extractor MCP

Table of Contents

• Features

• Use Cases

• Prerequisites

• Installation

• Configuration

• Usage with Claude Desktop, Claude Code, LiteLLM, and the Direct API

• Docker Compose

• Available MCP Tools

• Available Prompts

• Output Conventions: snake_case fields and ISO 8601 dates

• Cookie Management and Authentication

• Scope: metadata and transcripts only, no downloads

• Development

• License: MIT

Features

• Extract rich metadata from any yt-dlp-supported URL (YouTube, Vimeo, Twitch, and ~1800 more sites)

• Fetch transcripts with timestamps or as full text

• Search for media across supported platforms (supplementary discovery)

• Curated + raw output: focused summary at the top level, full yt-dlp info dict nested under raw

• Snake_case fields, ISO 8601 dates — matches yt-dlp's native format

• Optional two-layer auth: yt-dlp site credentials + bearer API key for your own endpoints

• Multiple transport options: stdio for Claude Desktop, SSE for web clients

• Direct API endpoint (POST /api) for quick testing without MCP protocol

• Persistent Python backend: no cold-start per call (imports yt-dlp once at startup)

Use Cases

• RAG over video — pull a video's transcript and metadata into a retrieval pipeline so an LLM can answer questions about the content without watching it.

• Summarize lectures, talks, and podcasts — feed the transcript to a model for key points, notable quotes, and takeaways (see the summarize_transcript prompt).

• Podcast & lecture indexing — extract titles, descriptions, chapters, and durations to build searchable catalogs of audio/video content.

• Accessibility via captions — retrieve subtitles (manual or auto-generated) in any available language for transcription and translation workflows.

• Channel & playlist research — expand a playlist or channel into structured per-video metadata for analysis, deduplication, or ranking.

• Media enrichment in search pipelines — pair with a web-search tool: discover candidate URLs, then enrich each one with full metadata and transcripts before summarization.

• Content discovery — use search_media to find videos on YouTube or Google Video by query, then drill into the ones that matter.

Prerequisites

• Node.js 18+

• Python 3.12+ (for standalone development)

• Docker + Docker Compose (for recommended deployment)

Installation

# Clone the repository
cd yt-media-info-mcp

# Install Node dependencies
npm install

# Build the Python service Docker image
docker compose build yt-dlp-service

Standalone Python service (without Docker)

If you want to run the Python service directly:

cd service
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

Then in another terminal:

YT_MEDIA_INFO_SERVICE_URL=http://localhost:8000 npm start

Configuration

Environment Variables

Copy .env.example to .env and customize. .env is gitignored — use .env.local for per-machine secrets not tracked by git.

Usage with Claude Desktop, Claude Code, LiteLLM, and the Direct API

Claude Desktop (stdio)

{
  "mcpServers": {
    "yt-dlp": {
      "command": "node",
      "args": ["/path/to/yt-media-info-mcp/src/index.js"],
      "env": {
        "ENABLE_SSE": "0"
      }
    }
  }
}

Claude Code (SSE)

{
  "mcpServers": {
    "yt-dlp": {
      "type": "sse",
      "url": "http://localhost:9423/sse"
    }
  }
}

LiteLLM

# config.yaml
model_list:
  - model_name: yt-dlp
    litellm_params:
      model: mcp
      mcp_servers:
        yt-dlp:
          transport: sse
          url: http://host.docker.internal:9423/sse

Direct API

The POST /api endpoint bypasses the MCP protocol and returns results directly:

# Extract info
curl -X POST http://localhost:9423/api \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "extract_info",
    "args": {
      "url": "https://www.youtube.com/watch?v=YE7VzlLtp-4"
    }
  }'

# Get transcript
curl -X POST http://localhost:9423/api \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_transcript",
    "args": {
      "url": "https://www.youtube.com/watch?v=YE7VzlLtp-4",
      "language": "en"
    }
  }'

# Search media
curl -X POST http://localhost:9423/api \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "search_media",
    "args": {
      "query": "python tutorial",
      "limit": 5
    }
  }'

Web clients (MCP SSE)

The server exposes standard MCP SSE endpoints:

// Connect via MCP SDK
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

const transport = new SSEClientTransport(new URL('http://localhost:9423/sse'));
const client = new Client({ name: 'web-app', version: '1.0' });
await client.connect(transport);

const result = await client.request(
  { method: 'tools/call', params: { name: 'extract_info', arguments: { url: 'https://www.youtube.com/watch?v=YE7VzlLtp-4' } } },
  resultSchema
);

Docker Compose

docker compose up -d           # start both services
docker compose logs -f         # tail logs
docker compose down            # stop
docker compose build           # rebuild after changes

The yt-dlp-service container is persistent and stays warm. The yt-media-info-mcp container waits for the health check on the Python service before accepting connections.

Available MCP Tools

extract_info

Extracts rich metadata from a media URL.

Parameters:

Output: Curated metadata (title, description, duration, uploader, statistics, chapters, thumbnails, formats summary, subtitles available, playlist info) + optional raw info dict.

get_transcript

Fetches subtitles or transcript text for a media URL.

Parameters:

Output: Language, duration, subtitle segments (with timestamps if requested), and concatenated full_text.

search_media

Supplementary discovery tool. Searches for media using yt-dlp's search prefixes (e.g. ytsearch:). This is a companion to general-purpose web search — it finds candidate URLs for further enrichment.

Parameters:

Output: Results array with url, title, duration_seconds, uploader, upload_date, thumbnail, view_count.

Available Prompts

• analyze_video: Analyze a video/media item from its available metadata (title, description, duration, uploader, categories, optional transcript summary).

• summarize_transcript: Summarize a video transcript to extract key points, notable quotes, and practical takeaways.

Output Conventions: snake_case fields and ISO 8601 dates

• snake_case field names (matches yt-dlp's native format)

• ISO 8601 date strings (e.g. "2024-01-15" for upload_date, "2024-01-15T14:30:00Z" for timestamps)

• Best-effort error handling: complete failures return an error response; missing fields are null; playlist entries that fail are collected in a failures array

Cookie Management and Authentication

When running in SSE mode, the server provides a web-based cookie upload form at http://<host>:<port>/ (default http://localhost:9423/) for uploading Netscape-format cookie files.

Web Upload Flow

1. Export cookies from your browser using yt-dlp:

   yt-dlp --cookies-from-browser chrome --cookies cookies.txt

   Or use a browser extension like Get cookies.txt LOCALLY.

2. Open the form at http://localhost:9423/ in your browser.

3. Upload the cookies.txt file — the form validates the file format, writes it atomically to the shared Docker volume at /data/cookies.txt, and displays parsed cookie info (domains, count, earliest expiry).

4. Delete cookies via the form's delete button when needed.

Endpoints

All endpoints are protected by the same YT_MEDIA_INFO_API_KEY bearer auth as the other HTTP endpoints (when configured).

Cookie File Format

The file must:

• Start with # Netscape HTTP Cookie File

• Be under 1 MB

• Use tab-separated Netscape cookie format

Cookie-bot Sidecar

If you have the cookie-bot sidecar running (opt-in via docker compose --profile cookies up -d), it will periodically refresh cookies from the shared volume. The web upload form is a convenient way to seed the initial cookie file — the cookie-bot then takes over automated refreshes.

Note: The cookie-bot's automated refresh will overwrite a manually uploaded file. Use the web form for initial seeding, then let the bot handle refreshes.

Scope: metadata and transcripts only, no downloads

This server does NOT download media files. It is a metadata enrichment and transcript extraction tool designed to work alongside other search and retrieval tools. No ffmpeg is required.

Development

npm run dev      # nodemon auto-restart
npm run lint     # ESLint
npm run lint:fix # ESLint auto-fix

License: MIT

This project is licensed under the MIT License.