Skip to main content
Glama
rutorrent-mcp

rutorrent-mcp

by abnormalend

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)

Related MCP server: Torrent Search MCP Server

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

Available Tools

13 tools
add_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

    A3.5/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    13 tools is appropriate for a torrent client server. It covers all essential operations without being bloated, providing a balanced scope for managing torrents.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers