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.

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

Env var	Required	Default
QBIT_MANAGE_URL	yes	-
QBIT_MANAGE_API_KEY	yes*	none (no API key header sent if unset)
QBIT_MANAGE_USERNAME	no	used for Basic auth when no API key is set
QBIT_MANAGE_PASSWORD	no	used for Basic auth when no API key is set

* 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.

Tool	Operations (endpoints)
qbit_manage_config	list_configs, get_config, create_config, update_config, delete_config, validate_config, backup_config, list_config_backups, restore_config_from_backup (/api/configs, /api/configs/{filename} + /validate, /backup, /backups, /restore)
qbit_manage_commands	run_command (/api/run-command)
qbit_manage_scheduler	get_scheduler_status, update_schedule, toggle_schedule_persistence (/api/scheduler, /api/schedule, /api/schedule/persistence/toggle)
qbit_manage_logs	get_logs, list_log_files, get_documentation (/api/logs, /api/log_files, /api/docs)
qbit_manage_system	get_version, health_check, get_base_url, force_reset_running_state (/api/version, /api/health, /api/get_base_url, /api/system/force-reset)
qbit_manage_security	get_security_settings, get_security_status, update_security_settings (/api/security, /api/security/status)

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

Command	Does
make sync	uv sync
make test	Offline tests - one per endpoint, mocked HTTP
make test-integration	Tests against the live instance (needs QBIT_MANAGE_URL/QBIT_MANAGE_API_KEY; write tests need QBIT_MANAGE_WRITE_TESTS=1)
make build	Build wheel + sdist into dist/
make bump-patch / bump-minor / bump-major	Bump the version in pyproject.toml + uv.lock
make clean	Remove build artifacts

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.