qbittorrent-mcp
Part of the arr-mcps collection.MCP server exposing qBittorrent'sWebUI 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 applicationsettings.
Built with FastMCP.
Enabling the API on your qBittorrent server
The WebUI API is enabled by default with the WebUI. You need WebUI accessenabled (Tools > Preferences > WebUI) and one of two auth methods:
- API key (qBittorrent >= v5.2.0 / WebAPI v2.14.1): generate one inPreferences > WebUI > API Key (format
qbt_<28 chars>). This is therecommended, stateless option. - Username/password: the WebUI login you'd use in the browser. Works on allversions.
Install
Download a wheel from the latest releaseand 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
| Env var | Required | Default |
|---|---|---|
QBITTORRENT_URL |
yes | - |
QBITTORRENT_API_KEY |
one of* | none (preferred) |
QBITTORRENT_USERNAME |
one of* | none (fall-back) |
QBITTORRENT_PASSWORD |
one of* | none (fall-back) |
* You must set either QBITTORRENT_API_KEY or both QBITTORRENT_USERNAME andQBITTORRENT_PASSWORD. If QBITTORRENT_API_KEY is set it wins; otherwise theserver logs in with the username/password on first use and reuses the sessioncookie, re-authenticating automatically if it expires.
Tools
10 resource-scoped tools, each covering multiple qBittorrent WebUIAPI v2 endpoints (90 total) via an operation parameter. Call a toolwith operation set to one of its listed operations and an argumentsdict matching that operation's parameters — the tool's own description(visible to your MCP client) lists every operation, its signature, and aone-line doc. This keeps the full API surface available while costing afraction of the context budget of registering all 90 endpoints asseparate tools.
| Tool | Operations | Kind |
|---|---|---|
qbittorrent_torrents |
22 | reads + writes |
qbittorrent_torrent_limits |
14 | reads + writes |
qbittorrent_rss |
12 | reads + writes |
qbittorrent_categories_tags |
10 | reads + writes |
qbittorrent_search |
10 | reads + writes |
qbittorrent_application |
9 | reads + writes |
qbittorrent_transfer |
8 | reads + writes |
qbittorrent_log |
2 | read-only |
qbittorrent_sync |
2 | read-only |
qbittorrent_auth |
1 | reads + writes |
Example: qbittorrent_torrents(operation="qbittorrent_torrents_pause", arguments={"hashes": "abc123"}).Endpoint-level naming (qbittorrent_<verb>_<resource>) is preserved as theoperation value, so the full endpoint list is still discoverable from eachgroup tool's description at runtime.
Development
make help # list all commands
| Command | Does |
|---|---|
make sync |
uv sync |
make test |
Offline tests - one per endpoint, mocked HTTP |
make test-integration |
Tests against the live instance (needs QBITTORRENT_URL + auth env) |
make build |
Build wheel + sdist into dist/ |
make bump-patch / bump-minor / bump-major |
Bump the version in pyproject.toml + uv.lock |
make clean |
Remove build artifacts |
The release workflow (.github/workflows/release.yml) builds and publishes toReleases whenever a v*tag is pushed - so the usual flow is make bump-patch, commit, then tag andpush.
The integration suite is read-only and never modifies your qBittorrent instance.
