rutorrent-mcp

MCP server for controlling rTorrent through ruTorrent's httprpc plugin — list/add/remove/start/stop torrents, manage labels and priorities, move data, and set global throttles from any MCP client.

Requirements

• Python 3.11+ and uv
• A ruTorrent install with the httprpc plugin enabled (default on most seedboxes)
• Optional plugins: diskspace (disk stats in global_stats), erasedata (needed for remove_torrent(delete_data=true) to actually delete files)

Configuration (environment variables)

Variable	Required	Default	Description
RUTORRENT_URL	yes	—	Base ruTorrent URL, e.g. https://host/rutorrent
RUTORRENT_USER	no	—	HTTP Basic auth username
RUTORRENT_PASSWORD	no	—	HTTP Basic auth password
RUTORRENT_TIMEOUT	no	30	HTTP timeout in seconds
RUTORRENT_VERIFY_SSL	no	true	Set false to skip TLS verification

Install with Claude Code

claude mcp add rutorrent \
  -e RUTORRENT_URL=https://host/rutorrent \
  -e RUTORRENT_USER=myuser \
  -e RUTORRENT_PASSWORD=mypass \
  -- uv run --directory /path/to/rutorrent_mcp rutorrent-mcp

Tools

Tool	Description
list_torrents	Compact list; filter by label/status, sort, limit
get_torrent	Full details; optional files/trackers/peers
global_stats	Rates, throttle limits, torrent count, disk space
add_torrent	Magnet/URL or local .torrent upload; label/dir/start options
remove_torrent	Remove; delete_data=true erases files (erasedata plugin)
start_torrent / stop_torrent / pause_torrent / recheck_torrent	Control by hash(es)
set_label / set_priority	Organization, bulk-capable
get_files	File list with indices, sizes, completion, priorities
set_file_priority	Per-file priority: off (skip) / normal / high
move_torrent	Move download directory, optionally moving data
set_throttle	Global KB/s limits, 0 = unlimited

rTorrent XML-RPC quirks

Per-file priority is not set over plain XML-RPC: f.set_priority is missing on some rTorrent builds and f.priority.set needs the HASH:f<index> target syntax, which varies by version. set_file_priority instead uses httprpc's form-urlencoded protocol (mode=setprio&hash=…&s=<prio>&v=<index>…) — the same path the ruTorrent web UI uses — and the PHP handler runs d.update_priorities afterwards. File priorities are a 3-level scale (0 = off/skip, 1 = normal, 2 = high), distinct from the 4-level torrent scale.

Development

uv sync
uv run pytest
# manual live check against a real seedbox:
RUTORRENT_URL=... RUTORRENT_USER=... RUTORRENT_PASSWORD=... uv run python scripts/smoke.py