Skip to main content
Glama
bubroz

zget

by bubroz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

zget

Agentic local media capture. Download and archive media from YouTube, Instagram, TikTok, Reddit, X, Twitch, C-SPAN, and other sites yt-dlp supports. Library with metadata, dedupe, path health, CLI, and MCP for agents and pipelines.

There is no web UI. Use the CLI or MCP.

Requirements

  • macOS or Linux

  • Python 3.10+

  • uv

  • ffmpeg

Related MCP server: webgrab-mcp

Install

curl -LsSf https://astral.sh/uv/install.sh | sh
brew install ffmpeg   # macOS

git clone https://github.com/bubroz/zget.git
cd zget
uv sync

Library path

Media and library.db live under ZGET_HOME:

  1. ZGET_HOME env

  2. ~/.config/zget/config.json key zget_home

  3. Default: ~/Downloads/zget

uv run zget config show
uv run zget config set zget_home /path/to/library
$ZGET_HOME/
  library.db
  videos/<platform>/
  thumbnails/
  exports/
  logs/

CLI

# download
uv run zget <url>
uv run zget <url> --quiet
uv run zget <url> --flat
uv run zget <url> -o /path/to/dir
uv run zget <url> --audio-only
uv run zget <url> --quality 720

# metadata only
uv run zget info <url>
uv run zget info <url> --json --compact
uv run zget --list-formats <url>
uv run zget list-channel <channel-or-playlist-url> --since 2020-01-01 --jsonl

# library
uv run zget --search "query"
uv run zget --stats
uv run zget --doctor
uv run zget --doctor --fix
uv run zget paths check
uv run zget paths rewrite --dry-run
uv run zget paths rewrite

# config
uv run zget config show
uv run zget config set flat true

C-SPAN

  • c-span.org/video/?... via yt-dlp

  • c-span.org/program/.../{id} via public HLS + Referer (src/zget/platforms/cspan.py)

  • c-span.org/event/.../{id} via C-SPAN API → child programs (multi-segment events download each)

  • If /api/events/… is WAF-blocked: open c-span.org in a browser, then --cookies-from chrome

Sidecars

Each successful download writes:

  • {stem}.librarian.json — capture provenance (url, sha256, duration, C-SPAN ids)

  • {stem}.nfo — Plex/Jellyfin (CLI and MCP ingest)

Path health

Class

Meaning

healthy

File exists under ZGET_HOME

relocatable

Stale path; file found after home or volume rename

off-home

File exists outside ZGET_HOME (pipeline -o)

offline volume

Unmounted /Volumes/... with no sibling match

orphan

File missing

--doctor --fix rewrites relocatable paths only. Use --purge-orphans only when you intend to drop missing rows.

Agents (MCP)

uv run zget-mcp
{
  "mcpServers": {
    "zget": {
      "command": "uv",
      "args": ["run", "zget-mcp"],
      "cwd": "/path/to/zget",
      "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }
    }
  }
}

Tool

Role

zget_download

Download URL into the library

zget_search

Full-text search

zget_get_video

Metadata by id

zget_get_local_path

Filesystem path for other tools

zget_extract_info

Metadata without download

zget_list_formats

Formats

zget_check_url

Already archived?

zget_get_recent

Recent downloads

zget_get_by_uploader

By channel

Full contract for other repos: docs/INTEGRATION.md.

Platforms

Verified: YouTube, Instagram, X, TikTok, Reddit, Twitch, C-SPAN (program + event pages). Many more via yt-dlp.

Layout

src/zget/
  core.py           # yt-dlp download / extract
  platforms/        # adapters (C-SPAN program/event HLS)
  metadata/         # .nfo + .librarian.json sidecars
  library/          # ingest, paths, thumbnails
  cli.py            # CLI
  mcp/              # MCP (stdio)
  db/               # SQLite FTS5
  metadata/         # NFO sidecars
  ...

Dev

uv sync --extra dev
uv run pytest
uv run ruff check src

License

MIT. Built on yt-dlp.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • webgrab-mcp

    bcefghj
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for web content downloading supporting videos, articles, danmaku, comments, and copy protection bypass across 1700+ sites.
    4
    MIT

  • watch-skill

    oxbshw
    A
    license
    Not graded
    quality
    A
    maintenance
    MCP server that enables AI agents to watch and analyze videos from 1800+ sources, with persistent indexing, OCR, transcription, and a self-verification loop for debugging.
    MIT

  • yt-media-info-mcp

    bartivs
    A
    license
    A
    quality
    A
    maintenance
    An MCP server that extracts rich metadata (title, description, duration, chapters, subtitles, statistics, etc.) from media URLs across thousands of sites using yt-dlp, and also provides transcript fetching and search capabilities.
    3
    MIT