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 | 简体中文

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"}
    }
  }
}

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)

Write (state-changing)

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

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