内容
# rutorrent-mcp
用于通过 ruTorrent 的 `httprpc` 插件控制 rTorrent —
列出/添加/删除/启动/停止种子、管理标签和优先级、移动数据、
从任何 MCP 客户端设置全局限速。
## 要求
- Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)
- 已安装 ruTorrent 并启用 `httprpc` 插件（大多数 seedbox 默认启用）
- 可选插件：`diskspace`（`global_stats` 中的磁盘统计）、`erasedata`
（需要 `remove_torrent(delete_data=true)` 才能实际删除文件）
## 配置（环境变量）
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `RUTORRENT_URL` | 是 | — | ruTorrent 基本 URL，例如 `https://host/rutorrent` |
| `RUTORRENT_USER` | 否 | — | HTTP 基本认证用户名 |
| `RUTORRENT_PASSWORD` | 否 | — | HTTP 基本认证密码 |
| `RUTORRENT_TIMEOUT` | 否 | `30` | HTTP 超时（秒） |
| `RUTORRENT_VERIFY_SSL` | 否 | `true` | 设置为 `false` 以跳过 TLS 验证 |
## 使用 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
```
## 工具
| 工具 | 描述 |
|---|---|
| `list_torrents` | 紧凑列表；按标签/状态筛选、排序、限制 |
| `get_torrent` | 完整详情；可选文件/跟踪器/对等方 |
| `global_stats` | 速率、限速限制、种子数量、磁盘空间 |
| `add_torrent` | 磁力/URL 或本地 `.torrent` 上传；标签/目录/启动选项 |
| `remove_torrent` | 删除；`delete_data=true` 删除文件（需要 erasedata 插件） |
| `start_torrent` / `stop_torrent` / `pause_torrent` / `recheck_torrent` | 按哈希控制 |
| `set_label` / `set_priority` | 组织，批量处理 |
| `get_files` | 文件列表，含索引、大小、完成度、优先级 |
| `set_file_priority` | 按文件优先级：`off`（跳过）/ `normal` / `high` |
| `move_torrent` | 移动下载目录，可选移动数据 |
| `set_throttle` | 全局 KB/s 限制，0 = 无限制 |
## rTorrent XML-RPC 特殊情况
通过纯 XML-RPC 无法设置文件优先级：`f.set_priority` 在某些 rTorrent 版本中缺失，
而 `f.priority.set` 需要 `HASH:f<index>` 目标语法，该语法因版本而异。
`set_file_priority` 改用 httprpc 的表单编码协议（`mode=setprio&hash=…&s=<prio>&v=<index>…`），
这是 ruTorrent 网页 UI 使用的协议，PHP 处理程序随后运行 `d.update_priorities`。
文件优先级为 3 级（0 = 关闭/跳过，1 = 正常，2 = 高），与种子 4 级优先级不同。
## 开发
```bash
uv sync
uv run pytest
# 对真实 seedbox 进行手动实时检查：
RUTORRENT_URL=... RUTORRENT_USER=... RUTORRENT_PASSWORD=... uv run python scripts/smoke.py
```
