# 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](https://docs.astral.sh/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

```bash
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

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