Repository avatar
Other Tools
v0.2.4
active

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.

CI PyPI Python Coverage License MCP qb-mcp MCP server

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_files is 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"}
    }
  }
}
FieldRequiredDefaultNotes
url✅—Must start with http:// or https://
username✅—Per-instance; instances may use different accounts
password✅—Literal, "${ENV_VAR}", or {"file": "/path"}
label—keyDisplay name
verify_ssl—trueSet false for self-signed certificates
timeout—8.0Per-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)

ToolPurpose
qb_instancesList configured instances and whether each is reachable
qb_overviewGlobal status for one or all instances
qb_listTorrent list with filtering, sorting and a row limit
qb_detailOne torrent in depth, including tracker status (tracker URLs are redacted unless show_tracker_urls=True)
qb_diagnoseExplain why an instance is or is not uploading

Write (state-changing)

ToolPurpose
qb_controlpause / resume / reannounce / force_start
qb_set_limitGlobal or per-torrent speed limits
qb_set_shareRatio / seeding-time / inactive-seeding-time limits (minutes) and the action taken on reaching them
qb_addAdd from magnet, URL or a local .torrent (paused by default)
qb_removeRemove torrents; delete_files is opt-in
qb_categoryAssign 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

qBittorrentWebUI APIStatus
4.x2.8+Supported
5.x2.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

Apache-2.0

PYPI
qb-mcp
Install Command
pip install qb-mcp
Runtime: uvx