
qb-mcp
io.github.zxw060810/qb-mcp
qBittorrent MCP server: eleven intent-shaped tools, multi-instance, version-aware calls.
Documentation
qb-mcp
An MCP server for qBittorrent — manage torrents with natural language.
This is an unofficial project. It is not affiliated with, endorsed by, or supported by the qBittorrent project.
English | 简体中文
Ask your agent "why isn't this torrent uploading?" and it can actually answer — tracker health, listening port, speed caps and peer supply, instead of guessing. Ask it to pause the seedbox and it knows qBittorrent 5.x renamed that endpoint.
qb-mcp wraps the qBittorrent WebUI API v2 and exposes it as eleven tools that
an AI agent can call. It manages any number of instances, each with its own
credentials, so a single agent can drive a home NAS and a remote seedbox at once.
Why this exists
qBittorrent has a complete HTTP API but no MCP interface. Wrapping it means an agent can answer "why isn't it uploading?" by actually checking tracker health, listening ports, speed limits and peer supply — instead of guessing.
The eleven tools are grouped by user intent, not by API endpoint: mapping all 80+ endpoints one-to-one would produce a tool list no model can choose from.
Features
- Multiple instances, each with independent credentials
qb_diagnose— turns "why is nothing uploading?" into one call- Field-trimmed responses — the API returns 30+ fields per torrent; this returns 12
- Before/after reporting on every write operation
delete_filesis opt-in — removing a torrent never deletes data by default- stdio and HTTP transports
- Credentials never leave your machine; nothing is logged
Quick start
pip install qb-mcp
cp instances.example.json .instances.json
# edit .instances.json with your qBittorrent URL and credentials
chmod 600 .instances.json
qb-mcp
Configuration
qb-mcp reads .instances.json from the current directory, or the path in
QB_MCP_CONFIG.
{
"instances": {
"nas": {
"label": "Home NAS",
"url": "http://192.168.1.100:8080",
"username": "admin",
"password": "${QB_PASS_NAS}"
},
"seedbox": {
"url": "https://seedbox.example.com",
"username": "me",
"password": {"file": "~/.secrets/seedbox"}
}
}
}
| Field | Required | Default | Notes |
|---|---|---|---|
url | ✅ | — | Must start with http:// or https:// |
username | ✅ | — | Per-instance; instances may use different accounts |
password | ✅ | — | Literal, "${ENV_VAR}", or {"file": "/path"} |
label | — | key | Display name |
verify_ssl | — | true | Set false for self-signed certificates |
timeout | — | 8.0 | Per-request timeout in seconds |
Keep .instances.json out of version control. It is already listed in
.gitignore. qb-mcp prints a warning if the file is readable by group or others.
Tools
Read (safe)
| Tool | Purpose |
|---|---|
qb_instances | List configured instances and whether each is reachable |
qb_overview | Global status for one or all instances |
qb_list | Torrent list with filtering, sorting and a row limit |
qb_detail | One torrent in depth, including tracker status (tracker URLs are redacted unless show_tracker_urls=True) |
qb_diagnose | Explain why an instance is or is not uploading |
Write (state-changing)
| Tool | Purpose |
|---|---|
qb_control | pause / resume / reannounce / force_start |
qb_set_limit | Global or per-torrent speed limits |
qb_set_share | Ratio / seeding-time / inactive-seeding-time limits (minutes) and the action taken on reaching them |
qb_add | Add from magnet, URL or a local .torrent (paused by default) |
qb_remove | Remove torrents; delete_files is opt-in |
qb_category | Assign categories and tags |
Client setup
stdio (Claude Desktop, Cursor, most local clients):
{
"mcpServers": {
"qbittorrent": {
"command": "qb-mcp",
"env": { "QB_MCP_CONFIG": "/absolute/path/to/.instances.json" }
}
}
}
HTTP (remote or multi-client):
qb-mcp --transport http --host 127.0.0.1 --port 17890
{
"servers": {
"qbittorrent": {
"url": "http://127.0.0.1:17890/mcp",
"transport": "streamable_http"
}
}
}
Compatibility
| qBittorrent | WebUI API | Status |
|---|---|---|
| 4.x | 2.8+ | Supported |
| 5.x | 2.11+ | Supported (tested on 5.2.4) |
Both official builds and third-party NAS packages (QNAP QPKG, Synology SPK) work, with the proxy quirks below already handled.
Troubleshooting
login rejected (Fails.)
qBittorrent returns HTTP 200 even when the password is wrong — the body is
Fails. instead of Ok.. qb-mcp inspects the body, so this message means the
credentials are genuinely wrong.
Login fails behind a reverse proxy
The official API requires Referer or Origin to match the request Host
exactly, including the port. qb-mcp sets both from your configured url,
so make sure url uses the same host and port you would type in a browser.
Works with curl but not through a proxy
Some reverse proxies (QNAP QTS is one) return 204 No Content with an empty
body on a successful login instead of 200 Ok.. qb-mcp treats any status
below 400 with an empty or Ok. body as success.
login blocked - too many failed attempts
qBittorrent temporarily bans an IP after repeated failures. Wait a few minutes, or check the WebUI's ban list.
Development
git clone https://github.com/zxw060810/qb-mcp.git
cd qb-mcp
pip install -e ".[dev]"
ruff check .
mypy src
pytest
Tests mock the qBittorrent API; no live instance is required.
License
qb-mcppip install qb-mcp