mediaclaw

MCP server and CLI for searching and downloading media across 22 sources. Works with Claude Desktop, Claude Code, and any MCP-compatible client.

Searches books, papers, movies, TV, anime, manga, music, games, ROMs, subtitles, and software — then downloads via direct HTTP, Real-Debrid, usenet, or torrent client.

Install

One command (npm)

npx mediaclaw setup

This runs the interactive wizard: configures downloads, registers the MCP server with Claude Desktop or Claude Code.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mediaclaw": {
      "command": "npx",
      "args": ["-y", "mediaclaw", "--mcp"]
    }
  }
}

Restart Claude Desktop. Done — ask Claude to search for anything.

Claude Code

claude mcp add mediaclaw -- npx -y mediaclaw --mcp

Standalone binary

Download from GitHub Releases — no Node/Bun required.

./mediaclaw search "sintel" --type=video
./mediaclaw --mcp   # start as MCP server

From source

git clone https://github.com/RZacharias44/mediaclaw && cd mediaclaw
bun install
bun run cli search "sintel"
claude mcp add mediaclaw -- bun run src/mcp.ts

Sources

| Source | Types | Config needed | |--------|-------|--------------| | LibGen (LG+) | books, papers, comics | - | | Sci-Hub | papers (DOI) | - | | Anna's Archive | books, papers, comics | - | | YTS | movies | - | | EZTV | TV episodes | - | | The Pirate Bay | everything | - | | Nyaa | anime, manga, audio | - | | Torrents-CSV | everything | - | | MangaDex | manga | - | | WeebCentral | manga, comics | - | | Comick | manga, comics | - | | FitGirl | games | - | | DODI | games | - | | Myrient | ROMs, retro games | - | | RomHeaven | ROMs | - | | MarioCube | GameCube/Wii | - | | Internet Archive | everything | - | | TorrentClaw | video | API key (optional) | | YTS-Subs | subtitles (movies) | - | | OpenSubtitles | subtitles | API key (free) | | Newznab indexers | everything | URL + API key | | Prowlarr | aggregator | URL + API key |

Known issues: YTS, EZTV, Comick, and YTS-Subs are currently down or unreliable. Run mediaclaw health to check live status. These sources fail gracefully — searches automatically fall back to working sources.

19 sources work with zero config. For downloads, optionally configure:

• Real-Debrid (~$3/mo) — cloud torrent downloading (recommended)
• Usenet — NZBGet (daemon or CLI) or SABnzbd
• Torrent client — qBittorrent or Transmission

MCP Tools

setup

Interactive onboarding. Shows current config status, helps configure download methods, writes config. Claude walks you through it conversationally.

setup()                                           // show what's configured
setup(config_updates: {realdebrid: {api_key: "..."}})  // write config

search

Search across all sources with optional type/format filtering.

search("machine learning", type: "book", format: "epub")
search("big buck bunny", type: "video")
search("10.1038/nature12373", type: "paper")

grab

Search + download the best result in one call.

grab("the rust programming language", type: "book")
grab("show name s01e01", type: "video")

download

Download a specific URL, magnet, or NZB. Routes automatically based on URL type:

• Direct HTTP → saved immediately
• Magnet/torrent → Real-Debrid or torrent client
• NZB → NZBGet or SABnzbd

download_status

Poll a Real-Debrid or usenet download for progress.

stream

Stream media in a video player. Searches, resolves, and plays — all in one call.

stream(query: "big buck bunny")                    // search + stream best result
stream(url: "magnet:?xt=urn:btih:...")            // stream a magnet via RD or webtorrent
stream(url: "https://rd-link.com/file.mkv")       // play a direct URL
stream(url: "~/Downloads/movie.mkv")              // play a local file
stream(query: "big buck bunny", player: "mpv")     // use a specific player

Routes automatically:

• Magnet + Real-Debrid → RD downloads, streams via direct HTTPS link (fastest)
• Magnet + no RD → webtorrent P2P streaming (needs webtorrent-cli)
• HTTP URL → opens player directly
• Local file → opens player directly

scan_file

Scan a downloaded file for security issues — magic byte mismatches, embedded executables, media codec validation via ffprobe.

health

Check which sources are reachable and their latency.

rate

Rate download quality after downloading. Feeds back into source ranking so future searches prefer sources that delivered good results.

suggest

When automated search fails, suggests manual sources and browse strategies for the media type you're looking for.

browse_for

Returns step-by-step browser instructions for manually finding content on sites that can't be scraped (e.g., sites behind Cloudflare). Includes URLs, selectors, and tips.

stats

Show usage statistics — searches performed, downloads completed, source hit rates.

CLI

mediaclaw search "machine learning" --type=book
mediaclaw stream "big buck bunny" --player=vlc
mediaclaw scan ~/Downloads/file.mkv
mediaclaw health
mediaclaw stats
mediaclaw setup
mediaclaw contribute check libgen   # diagnose a broken source
mediaclaw contribute add mysite https://example.com  # scaffold new source
mediaclaw contribute pr             # fork + commit + open PR
mediaclaw --mcp   # start MCP server

Config

~/.config/mediaclaw/config.json:

{
  "download_dir": "~/Downloads",

  // Torrent downloads via Real-Debrid
  "realdebrid": {
    "api_key": "YOUR_KEY",
    "prefer": true
  },

  // Usenet downloads (pick one)
  "usenet": {
    "type": "sabnzbd",           // "nzbget", "nzbget-cli", or "sabnzbd"
    "url": "http://localhost:8080",
    "api_key": "YOUR_KEY"
  },

  // Newznab usenet indexers
  "sources": {
    "newznab": [
      { "name": "nzbgeek", "url": "https://api.nzbgeek.info", "api_key": "YOUR_KEY" }
    ],
    "opensubtitles": { "api_key": "YOUR_KEY" }
  },

  // Media player for streaming (auto-detected if omitted)
  "player": "vlc",  // "vlc", "mpv", "iina"

  // Subtitle language preference
  "subtitle_languages": ["english"],

  // Customize which sources are queried per media type
  "fallbacks": {
    "video": ["yts", "eztv", "tpb", "nyaa", "torrentscsv"],
    "book": ["libgen", "annas-archive", "internetarchive"],
    "subtitle": ["ytssubs", "opensubtitles"]
  }
}

Any source can be disabled by setting it to false in sources:

{ "sources": { "tpb": false } }

Usenet setup

NZBGet CLI (lightest — no daemon needed):

{
  "usenet": { "type": "nzbget-cli" }
}

Requires brew install nzbget and a ~/.nzbget config with your usenet server credentials.

NZBGet daemon:

{
  "usenet": {
    "type": "nzbget",
    "url": "http://localhost:6789",
    "username": "nzbget",
    "password": "tegbzn6789"
  }
}

SABnzbd:

{
  "usenet": {
    "type": "sabnzbd",
    "url": "http://localhost:8080",
    "api_key": "YOUR_SAB_API_KEY"
  }
}

How it works

1. Search queries Prowlarr first (if configured), then falls back to type-specific sources
2. Results are deduplicated by info hash/URL and ranked by seeders or source priority
3. Download routes based on download_method on each result:
   • direct — HTTP download (LibGen, Sci-Hub, Anna's Archive, Internet Archive, OpenSubtitles)
   • magnet/torrent — sent to Real-Debrid or torrent client
   • nzb — sent to NZBGet or SABnzbd
4. Sources with interstitial pages (LibGen ads.php) have custom resolve() handlers

Development

bun install          # Install dependencies
bun run dev          # Start MCP server (stdio)
bun run cli search "sintel"  # Run CLI from source
bun run typecheck    # TypeScript type check
bun test             # Run all tests (136 tests across 14 files)
bun run build        # Bundle dist/mcp.js + dist/cli.js

Tests

• 136 unit tests across 14 files — fixture-based, no network needed
• 18 integration tests — live source searches and download flows (auto-skip when services aren't configured)
• Manual test script — ./tests/manual-test.sh for end-to-end walkthrough

Integration tests gracefully skip when optional services (Real-Debrid, usenet, torrent client) aren't configured.

Project structure

src/
  mcp.ts              # MCP server entry point
  cli.ts              # CLI entry point
  config.ts           # Config loading (~/.config/mediaclaw/config.json)
  types.ts            # Shared types (Source, SearchResult, MediaType, etc.)
  sources/            # 22 source implementations + template
  mcp/                # MCP server setup + tool registrations
  tools/              # Tool implementations (search, download, scan, etc.)
  download/           # Download handlers (Real-Debrid, usenet, torrent)
  scan/               # File scanning (magic bytes, ffprobe, Claude eval)
  stream.ts           # Streaming (RD, webtorrent, direct)
  utils/              # Shared utilities
tests/
  *.test.ts           # Unit tests with fixtures
  integration/        # Live integration tests
  fixtures/           # HTML/JSON/XML response fixtures

Contributing

mediaclaw has a built-in contribution system designed for both humans and Claude instances. When a source breaks, the tool can detect it and guide a fix.

Enable nudges — when sources fail, MCP responses include [contribute] hints:

{ "contribute": { "enabled": true, "mode": "suggest" } }

Diagnose a broken source:

mediaclaw contribute check libgen    # health check + test search

Scaffold a new source:

mediaclaw contribute add mysite https://example.com
# Creates src/sources/mysite.ts from template

Submit a fix:

mediaclaw contribute pr    # fork, commit, push, open PR (needs gh CLI)

See CONTRIBUTING.md for the full guide.

License

MIT