rutorrent-mcp
This MCP server enables full management of a ruTorrent/rTorrent instance via ruTorrent's httprpc plugin.
Monitor & Retrieve Information
Global stats (
global_stats): View transfer rates, throttle limits, torrent counts, and disk space.List torrents (
list_torrents): Get a compact torrent list with filtering by label/status and sorting.Get torrent details (
get_torrent): Fetch full info for a specific torrent by hash, optionally including files, trackers, and peers.Get file list (
get_files): View file details including indices, sizes, completion, and priorities.
Manage Torrent Lifecycle
Add torrents (
add_torrent): Add via magnet link, URL, or local.torrentfile, with optional label, download directory, and start/stop control.Remove torrents (
remove_torrent): Remove one or more torrents, with optional data deletion (requireserasedataplugin).Start/Stop/Pause/Recheck (
start_torrent,stop_torrent,pause_torrent,recheck_torrent): Control torrent state by info-hash(es).
Organize & Prioritize
Set labels (
set_label): Assign or clear labels on one or more torrents.Set torrent priority (
set_priority): Set bandwidth priority (off,low,normal,high).Set file priority (
set_file_priority): Set per-file priority (off,normal,high) within a torrent.Move torrents (
move_torrent): Move a torrent to a new directory, optionally moving the data on disk.
Global Settings
Set throttle (
set_throttle): Set global upload/download speed limits in KB/s (0 = unlimited).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rutorrent-mcp list all torrents with label 'linux iso'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
httprpcplugin enabled (default on most seedboxes)Optional plugins:
diskspace(disk stats inglobal_stats),erasedata(needed forremove_torrent(delete_data=true)to actually delete files)
Related MCP server: Torrent Search MCP Server
Configuration (environment variables)
Variable | Required | Default | Description |
| yes | — | Base ruTorrent URL, e.g. |
| no | — | HTTP Basic auth username |
| no | — | HTTP Basic auth password |
| no |
| HTTP timeout in seconds |
| no |
| Set |
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-mcpTools
Tool | Description |
| Compact list; filter by label/status, sort, limit |
| Full details; optional files/trackers/peers |
| Rates, throttle limits, torrent count, disk space |
| Magnet/URL or local |
| Remove; |
| Control by hash(es) |
| Organization, bulk-capable |
| File list with indices, sizes, completion, priorities |
| Per-file priority: |
| Move download directory, optionally moving data |
| 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.pyAvailable Tools
13 toolsadd_torrentA
Add a torrent from a magnet link / URL, or upload a local .torrent file.
Provide exactly one of magnet_or_url or file_path. Optional label and download directory. start=False adds it stopped.
Addition is not verified by rTorrent; check with list_torrents afterwards.
Inputs: label, start, directory, file_path, +1 more.
get_torrentC
Full details for one torrent by info-hash.
Inputs: hash (required), include_files, include_peers, include_trackers.
global_statsA
Global transfer rates, throttle limits, torrent count, and disk space.
Inputs: no named parameters.
list_torrentsA
List torrents with compact per-torrent info.
Filters: label (exact match), status. Sorted by sort_by (name ascending,
numeric keys descending). Returns at most limit torrents plus the total
match count.
Inputs: label, limit, status, sort_by.
move_torrentA
Move a torrent to another download directory.
Stops the torrent, optionally moves its data on the seedbox (requires rTorrent's execute permission, standard on seedboxes), points rTorrent at the new location, and restarts it if it was running.
Inputs: hash (required), directory (required), move_data.
pause_torrentB
Pause torrents (stays open, transfers halt; resume with start_torrent).
Inputs: hashes (required).
recheck_torrentC
Force a hash re-check of downloaded data.
Inputs: hashes (required).
remove_torrentA
Remove torrents. delete_data=True also erases downloaded files (requires ruTorrent's erasedata plugin; otherwise files remain on disk).
Inputs: hashes (required), delete_data.
set_labelB
Set the ruTorrent label on torrents. Empty string clears the label.
Inputs: label (required), hashes (required).
set_priorityA
Set torrent bandwidth priority: off (do not transfer), low, normal, or high.
Inputs: hashes (required), priority (required).
set_throttleA
Set global download/upload speed limits in KB/s. 0 means unlimited.
Inputs: upload_kbps, download_kbps.
start_torrentC
Start (resume) torrents by info-hash.
Inputs: hashes (required).
stop_torrentA
Stop torrents (closes them; no seeding, no connections).
Inputs: hashes (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose: adding, retrieving, listing, moving, pausing, rechecking, removing, labeling, prioritizing, throttling, starting, stopping, and global stats. No overlap exists between their functionalities.
Almost all tools follow the verb_noun pattern (add_torrent, get_torrent, etc.). The only exception is 'global_stats', which breaks the pattern but is still clear and understandable.
13 tools is appropriate for a torrent client server. It covers all essential operations without being bloated, providing a balanced scope for managing torrents.
The tool set covers the full lifecycle of torrent management: add, start, stop, pause, remove, move, recheck, and retrieve details. Minor gaps exist, such as per-torrent speed limits, but overall it's robust for typical use cases.
Maintenance
Related MCP Connectors
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceA Python MCP server that allows programmatic interaction with YggTorrent, enabling torrent search, details retrieval, and magnet link generation without exposing your Ygg passkey.418MIT
- AlicenseAqualityBmaintenanceA Python MCP server that allows programmatic interaction to find torrents programmatically on ThePirateBay, Nyaa and YggTorrent.7151 PyPI45PythonMIT
- AlicenseBqualityDmaintenancePython wrapper & MCP server for the rqbit API83MIT
- AlicenseAqualityDmaintenanceMCP server for managing Transmission BitTorrent client. Provides tools to add, remove, monitor, and control torrents, as well as configure session settings.151MIT