torrent-mcp

A personal movie/series torrent-queue pipeline — IMDb list scraping, OMDb title lookups, Jackett search, and qBittorrent RSS queue management — as a tested Python library, a CLI, and an MCP server so a natural-language client (a Telegram bot, Claude Desktop, etc.) can drive the whole thing in plain English.

This replaces a folder of ad hoc scripts (B6_imdb-torrents/) that each hardcoded one person's Jackett API key, OMDb key, LAN IP, and /home/b/... paths directly in source. All of that is now environment configuration — see .env.sample — so the code itself has nothing sensitive in it.

What it does

list_profiles (MCP only) reports which queue profiles are configured.

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

Copy .env.sample to .env and fill in your own OMDB_API_KEY, JACKETT_URL/JACKETT_API_KEY, and TORRENT_MCP_PROFILES (one entry per qBittorrent+Jackett RSS queue — movies, series, upgrades, ...). See the comments in .env.sample for every setting.

CLI

torrent-mcp find-candidates "https://www.imdb.com/list/ls0123456789/"
torrent-mcp check-candidates movies tt1375666 tt0111161
torrent-mcp add-to-queue movies tt1375666 --indexer yts
torrent-mcp list-queue movies --resolve-titles
torrent-mcp switch-indexer movies yts torrentgalaxy
torrent-mcp lookup tt1375666
torrent-mcp --help   # full command list

MCP server

torrent-mcp-server

Runs over stdio, ready for any MCP client (Claude Desktop, the MCP Inspector, a custom client) to spawn as a subprocess. Example claude_desktop_config.json entry:

{
  "mcpServers": {
    "torrent-mcp": {
      "command": "/absolute/path/to/.venv/bin/torrent-mcp-server",
      "env": { "OMDB_API_KEY": "...", "JACKETT_API_KEY": "...", "...": "..." }
    }
  }
}

Integration with ocabra_telegram

ocabra_telegram drives this server the same way it already drives homebox_mcp — over stdio via a small JSON-RPC client (homebox_tools.McpStdioClient, reused as-is by its torrent_tools.py) and bot.py's call_ocabra_with_tools tool-calling loop, which now runs over whichever backends (Homebox, torrent-mcp, both) are active for the current user. See that repo's README, "Torrent Queue Integration", for the TORRENT_MCP_* env vars to set there. Once wired, Telegram messages like "what's queued for movies?" or "add tt1375666 to the movies queue" drive this project directly — this project only owns the MCP server side; the client-side wiring lives in ocabra_telegram.

Development

pip install -e ".[dev]"
pytest

Tests mock all external HTTP (OMDb, Jackett, IMDb) with respx and use tmp_path for filesystem operations — nothing touches the network or a real queue.

Notes on the original scripts

• manage_queue/queue_get-titles.py used imdbpy to scrape IMDb directly for titles; this project uses OMDb everywhere instead (already needed for other lookups), so there's one metadata dependency, not two.

• The ten near-identical switchindexer_*.sh scripts (one hardcoded path + container per direction) are now one switch-indexer command parameterized by profile and indexer names.

• trackers/check_imdbsearch.py logged into Jackett's dashboard with an admin password before calling its API; the API calls it made only ever needed the API key, so that login step (and the password) is gone.

• Nothing here runs sudo or shells out to docker unless DOCKER_RESTART_ENABLED=true, and then only for a container name from your own TORRENT_MCP_PROFILES config — never a name supplied through a tool call.