qbit_manage-mcp

Part of the arr-mcps collection. MCP server exposing qbit_manage's Web API as tools, so an LLM can read and manage a qbit_manage instance: run maintenance commands against your qBittorrent torrents, manage config files (create/read/update/delete/validate/backup/restore), the scheduler, logs, security settings, and system state.

Built with FastMCP. qbit_manage's API has no vendored OpenAPI spec, so the endpoint table is hand-maintained against qbit_manage's modules/web_api.py handler routes (see AGENTS.md).

Enabling the Web API on your qbit_manage server

qbit_manage's REST API runs at port 8181 by default. Start it with the web server enabled, e.g. qbit_manage --web-server --host 0.0.0.0 --port 8181 (or set QBT_WEB_SERVER=true / QBT_HOST / QBT_PORT in Docker). See qbit_manage's Web-API docs for details.

Related MCP server: profilarr-mcp

Install

Download a wheel from the latest release and install it as a uv tool (no repo checkout needed):

uv tool install qbit_manage_mcp-*.whl

This puts a qbit-manage-mcp command on your PATH. Register it with Claude Code:

claude mcp add qbit-manage \
  --env QBIT_MANAGE_URL=http://qbit-manage.example.com:8181 \
  --env QBIT_MANAGE_API_KEY=<key> \
  -- qbit-manage-mcp

From source

uv sync
cp .env.example .env   # fill in QBIT_MANAGE_URL and QBIT_MANAGE_API_KEY

claude mcp add qbit-manage \
  --env QBIT_MANAGE_URL=http://qbit-manage.example.com:8181 \
  --env QBIT_MANAGE_API_KEY=<key> \
  -- uv run --directory /path/to/qbit_manage-mcp qbit-manage-mcp

Config

* If authentication is enabled on qbit_manage (method: api_only or basic) you must set the API key (or username/password), or every authenticated call returns 401. If authentication is disabled or bypass_auth_for_local is on, the server still works without credentials. If your qbit_manage instance is served under a base URL (--base-url/QBT_BASE_URL), include that subpath in QBIT_MANAGE_URL.

Tools

Six resource-scoped tools. Each takes an operation (one of the listed endpoints) plus an arguments dict matching that operation's parameters, and dispatches to the underlying endpoint. This is the fleet's portmanteau pattern: all 23 qbit_manage endpoints wrapped as 6 tools so every session's system prompt stays small.

run_command is how an LLM triggers actual qbit_manage work against qBittorrent: pass a body with commands (e.g. ["cat_update", "tag_update"]), optionally hashes to scope to specific torrents, and dry_run: true to preview without side effects. Valid commands: cat_update, tag_update, recheck, rem_unregistered, tag_tracker_error, rem_orphaned, tag_nohardlinks, share_limits.

Config write operations take the config data as {"data": <config dict>} — data mirrors the YAML structure. get_documentation returns raw markdown text, not JSON.

Development

make help  # list all commands

The release workflow (.github/workflows/release.yml) builds and publishes to Releases whenever a v* tag is pushed - so the usual flow is make bump-patch, commit, then tag and push.