qb-mcp
Integrates with the qBittorrent WebUI API v2 to manage any number of qBittorrent instances, including listing and inspecting torrents, diagnosing upload issues, pausing/resuming/reannouncing torrents, setting speed and share limits, adding or removing torrents, and assigning categories and tags.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
Related MCP server: Transmission MCP Server
Features
Multiple instances, each with independent credentials
qb_diagnose— turns "why is nothing uploading?" into one callField-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 defaultstdio 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-mcpConfiguration
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 |
| ✅ | — | Must start with |
| ✅ | — | Per-instance; instances may use different accounts |
| ✅ | — | Literal, |
| — | key | Display name |
| — |
| Set |
| — |
| 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 |
| List configured instances and whether each is reachable |
| Global status for one or all instances |
| Torrent list with filtering, sorting and a row limit |
| One torrent in depth, including tracker status (tracker URLs are redacted unless |
| Explain why an instance is or is not uploading |
Write (state-changing)
Tool | Purpose |
|
|
| Global or per-torrent speed limits |
| Ratio / seeding-time / inactive-seeding-time limits (minutes) and the action taken on reaching them |
| Add from magnet, URL or a local |
| Remove torrents; |
| 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
pytestTests mock the qBittorrent API; no live instance is required.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
YouTube transcripts, search, channels, playlists and bulk transcript jobs for AI agents. 14 tools.
17 pay-per-call web, finance, legal and onchain tools for AI agents. USDC on Base via x402/MPP.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA service that provides programmatic access to qBittorrent's WebUI API, enabling management of torrents, trackers, tags, speed controls, and system information through natural language.29-
- AlicenseNot gradedqualityDmaintenanceProvides tools for interacting with the Transmission BitTorrent client via natural language, enabling users to manage torrents, configure download settings, and monitor download activity.3MIT
- FlicenseAqualityDmaintenanceEnables interaction with qBittorrent through its Web API to search for torrents using search plugins and manage downloads. Supports torrent searching, downloading via URLs/magnet links, and torrent management operations like pause, resume, and delete.73-
- AlicenseAqualityCmaintenanceMCP server exposing qBittorrent's WebUI API v2 as tools, enabling LLMs to manage torrents, categories, tags, RSS feeds, search plugins, and application settings.903MIT