qbittorrent-mcp

Part of the arr-mcps collection. MCP server exposing qBittorrent's WebUI API v2 (qBittorrent >= 5.0) as tools, so an LLM can manage your torrents: list, inspect properties/trackers/files, add/pause/resume/delete torrents, manage categories, tags, RSS feeds and search plugins, and tweak application settings.

Built with FastMCP.

Enabling the API on your qBittorrent server

The WebUI API is enabled by default with the WebUI. You need WebUI access enabled (Tools > Preferences > WebUI) and one of two auth methods:

• API key (qBittorrent >= v5.2.0 / WebAPI v2.14.1): generate one in Preferences > WebUI > API Key (format qbt_<28 chars>). This is the recommended, stateless option.

• Username/password: the WebUI login you'd use in the browser. Works on all versions.

Install

Download a wheel from the latest release and install it as a uv tool (no repo checkout needed):

uv tool install qbittorrent_mcp-*.whl

This puts a qbittorrent-mcp command on your PATH. Register it with Claude Code:

claude mcp add qbittorrent \
  --env QBITTORRENT_URL=http://localhost:8080 \
  --env QBITTORRENT_API_KEY=<key> \
  -- qbittorrent-mcp

Or with username/password:

claude mcp add qbittorrent \
  --env QBITTORRENT_URL=http://localhost:8080 \
  --env QBITTORRENT_USERNAME=admin \
  --env QBITTORRENT_PASSWORD=<password> \
  -- qbittorrent-mcp

From source

uv sync
cp .env.example .env   # fill in QBITTORRENT_URL and an auth method

claude mcp add qbittorrent \
  --env QBITTORRENT_URL=http://localhost:8080 \
  --env QBITTORRENT_API_KEY=<key> \
  -- uv run --directory /path/to/qbittorrent-mcp qbittorrent-mcp

Config

* You must set either QBITTORRENT_API_KEY or both QBITTORRENT_USERNAME and QBITTORRENT_PASSWORD. If QBITTORRENT_API_KEY is set it wins; otherwise the server logs in with the username/password on first use and reuses the session cookie, re-authenticating automatically if it expires.

Tools

10 resource-scoped tools, each covering multiple qBittorrent WebUI API v2 endpoints (90 total) via an operation parameter. Call a tool with operation set to one of its listed operations and an arguments dict matching that operation's parameters — the tool's own description (visible to your MCP client) lists every operation, its signature, and a one-line doc. This keeps the full API surface available while costing a fraction of the context budget of registering all 90 endpoints as separate tools.

Example: qbittorrent_torrents(operation="qbittorrent_torrents_pause", arguments={"hashes": "abc123"}). Endpoint-level naming (qbittorrent_<verb>_<resource>) is preserved as the operation value, so the full endpoint list is still discoverable from each group tool's description at runtime.

Development

make help  # list all commands

The release workflow (.github/workflows/release.yml) builds and publishes to Releases whenever a v* tag is pushed - so the usual flow is make bump-patch, commit, then tag and push.

The integration suite is read-only and never modifies your qBittorrent instance.