Listed from the MCP registry; nobody on Odel publishes it.
qBittorrent MCP server: eleven intent-shaped tools, multi-instance, version-aware calls.
Runs on your machine from its package; the steps are below.
Not assessed yet.
Odel charges nothing per call. The publisher may charge for its own service.
Runs locally over stdio
This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).
Run
uvx qb-mcp
MCP client config
{
"mcpServers": {
"qbittorrent": {
"command": "uvx",
"args": [
"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.
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.
qb_diagnose — turns "why is nothing uploading?" into one calldelete_files is opt-in — removing a torrent never deletes data by defaultpip install qb-mcp
cp instances.example.json .instances.json
# edit .instances.json with your qBittorrent URL and credentials
chmod 600 .instances.json
qb-mcp
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.
| 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 |
| 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 |
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"
}
}
}
| 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.
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.
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.
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 attemptsqBittorrent temporarily bans an IP after repeated failures. Wait a few minutes, or check the WebUI's ban list.
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.