MCP server for qBittorrent: manage torrents, categories, and transfer info via the WebUI API with cookie-session auth
Server has 11 well-named tools with complete input schemas and descriptions. Naming follows verb_noun convention (get_, list_, add_, pause_, resume_, delete_, set_, toggle_). Descriptions are present and actionable (avg ~120 chars). However, output schemas are not documented, LLMs cannot predict response structure. Error handling is minimal (generic HTTP errors, no recovery guidance). Parameters lack enums for constrained values (e.g., 'filter' accepts free-form strings instead of enum). No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels. Missing pagination support on list tools. Responses likely include raw API fields without stripping irrelevant metadata.
Add a torrent from a magnet link.
Delete one or more torrents. Optionally also delete downloaded files.
List all torrent categories with their save paths.
Get detailed properties for a specific torrent by hash.
List all torrents with status, progress, speed, seeds, and peers. Optionally filter by state (downloading, uploading, paused, completed, active, inactive, stalled, error).
Get global transfer statistics: download/upload speeds, session and all-time totals, connection count, DHT nodes.
No output schemas documented. LLMs cannot predict response structure, field names, or types. Downstream tool chaining is error-prone.
Filter and sort parameters accept free-form strings instead of enums. LLMs will hallucinate invalid values (e.g., 'filter: downloading_fast'). Should declare enums: filter: [all, downloading, seeding, completed, paused, active, inactive, stalled, stalled_uploading, stalled_downloading, error].
No tool annotations (readOnlyHint, destructiveHint, idempotentHint). Tools are marked with Risk levels in metadata but not exposed to LLM via schema. Clients cannot distinguish safe reads from destructive deletes.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | 2026-07-28+ | v2 |
Pause one or more torrents. Use 'all' to pause everything.
Resume one or more paused torrents. Use 'all' to resume everything.
Set global download and/or upload speed limits. Pass 0 to remove a limit.
Assign a category to one or more torrents.
Toggle the alternative (throttled) speed limits on or off.
Error handling is minimal. Generic HTTP error messages (e.g., 'API error 403 on GET /torrents') provide no recovery guidance. Should return actionable errors: 'Session expired. Retrying login...' or 'Invalid torrent hash. Use 8-char prefix from qbittorrent_get_torrents.'
List tools (qbittorrent_get_torrents, qbittorrent_get_categories) lack pagination. No limit, offset, or cursor parameters. Large torrent lists will blow context window.