Skip to main content
Glama

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

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.

Available Tools

6 tools
qbit_manage_commandsA

qbit manage commands operations on qbit_manage. Pass operation and an arguments dict matching that operation's parameters.

  • qbit_manage_run_command(body={}) — Run qbit_manage commands against a config (body is a CommandRequest: config_file, commands list, hashes, dry_run, skip_cleanup, skip_qb_version_check, log_level). Valid commands: cat_update, tag_update, recheck, rem_unregistered, tag_tracker_error, rem_orphaned, tag_nohardlinks, share_limits. WRITE: this runs real qbit_manage operations against your qBittorrent instance.

Inputs: operation (required), arguments. Returns: result

qbit_manage_configA

qbit manage config operations on qbit_manage. Pass operation and an arguments dict matching that operation's parameters.

  • qbit_manage_backup_config(filename) — Create a timestamped manual backup of a config file (keeps up to 30 per config). WRITE: this modifies your qbit_manage instance.

  • qbit_manage_create_config(filename, body={}) — Create a new config file (body is {"data": }). Returns 409 if the file already exists. WRITE: this modifies your qbit_manage instance.

  • qbit_manage_delete_config(filename) — Delete a config file permanently (a backup is created before deletion). DESTRUCTIVE: this deletes data.

  • qbit_manage_get_config(filename) — Fetch a parsed config file. data mirrors the YAML structure; !ENV references are preserved as "!ENV ".

  • qbit_manage_list_config_backups(filename) — List available backups for a config file, newest first.

  • qbit_manage_list_configs() — List available config files in the config directory (sensitive files like qbm_settings.yml are filtered out).

  • qbit_manage_restore_config_from_backup(filename) — Load a backup by name (filename is the backup file name in the path, e.g. config_20260521_100000.yml) and return its data for restoring.

  • qbit_manage_update_config(filename, body={}) — Update an existing config file (body is {"data": }); a timestamped backup is auto-created before writing. WRITE: this modifies your qbit_manage instance.

  • qbit_manage_validate_config(filename, body={}) — Validate a config through the parser without executing (body is {"data": }); defaults backfilled during validation are written back to the real config.

Inputs: operation (required), arguments. Returns: result

qbit_manage_logsA
Read-only

qbit manage logs operations on qbit_manage. Pass operation and an arguments dict matching that operation's parameters.

  • qbit_manage_get_documentation(file) — Fetch a markdown docs file by name (e.g. Home.md, Commands.md, Config-Setup.md). Returns markdown text, not JSON.

  • qbit_manage_get_logs(limit=None, log_filename=None) — Fetch recent log lines in chronological order. limit caps the tail; log_filename selects the active (.log) or rotated (..log) file (default qbit_manage.log).

  • qbit_manage_list_log_files() — List available log files (active and rotated).

Inputs: operation (required), arguments. Returns: result

qbit_manage_schedulerA

qbit manage scheduler operations on qbit_manage. Pass operation and an arguments dict matching that operation's parameters.

  • qbit_manage_get_scheduler_status() — Return scheduler status: current schedule (type interval|cron + value), next run time, is_running, source, persistent/file_exists/disabled state.

  • qbit_manage_toggle_schedule_persistence() — Toggle whether the schedule persists across restarts. WRITE: this modifies your qbit_manage instance.

  • qbit_manage_update_schedule(body={}) — Set the schedule (body {"schedule": "1440" or "0 4 * * *", "type": "interval" or "cron" optional}). Takes effect immediately; type auto-detected if omitted. WRITE: this modifies your qbit_manage instance.

Inputs: operation (required), arguments. Returns: result

qbit_manage_securityA

qbit manage security operations on qbit_manage. Pass operation and an arguments dict matching that operation's parameters.

  • qbit_manage_get_security_settings() — Get security settings (API key and password hash are redacted).

  • qbit_manage_get_security_status() — Get auth summary without sensitive data: has_api_key, method, enabled.

  • qbit_manage_update_security_settings(body={}) — Update security settings (body is a SecuritySettingsRequest: enabled, method none|basic|api_only, username, password, generate_api_key, clear_api_key, trusted_proxies, bypass_auth_for_local, current_* credentials for reauthentication). WRITE: this modifies your qbit_manage instance.

Inputs: operation (required), arguments. Returns: result

qbit_manage_systemA

qbit manage system operations on qbit_manage. Pass operation and an arguments dict matching that operation's parameters.

  • qbit_manage_force_reset_running_state() — Force-reset the internal is_running flag to recover from a stuck run state. WRITE: this modifies your qbit_manage instance.

  • qbit_manage_get_base_url() — Return the configured base URL the web server is served under (always public).

  • qbit_manage_get_version() — Get the current qbit_manage version with update availability details (always public).

  • qbit_manage_health_check() — Liveness/readiness probe (always public): status healthy|degraded|busy|unhealthy, queue size, config/log directory state, next scheduled run.

Inputs: operation (required), arguments. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    The six tools are clearly separated by resource domain: config, commands, scheduler, logs, system, and security. There is no meaningful overlap in purpose, so an agent can reliably choose the right tool.

    Naming Consistency5/5

    Every tool follows the same qbit_manage_<noun> snake_case pattern. The naming is uniform and predictable, making tool selection and routing straightforward.

    Tool Count5/5

    Six tools is a well-scoped count for managing a qbit_manage instance. Each tool represents a distinct functional area without unnecessary proliferation or overlap.

    Completeness5/5

    The tool surface covers config lifecycle, backup/restore, validation, command execution, scheduling, logs, system health/version, and security settings. These are the core domains needed to operate and manage a qbit_manage server, with no obvious critical gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server exposing a local (or LAN) ComfyUI instance's HTTP API as tools, so an LLM client can queue generations, inspect the queue/history, upload reference images, browse installed models/nodes, and pull back generated images.
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server exposing Profilarr's v1 REST API as tools, enabling an LLM to inspect and manage linked databases, connected Radarr/Sonarr instances, backups, jobs, announcements, and system status.
      20
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server that exposes qui's JSON REST API as tools for monitoring and managing qBittorrent instances, torrents, automations, cross-seeding, RSS, backups, and related services.
      12
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server exposing Dashbrr's REST API as tools, so an LLM can read and manage a dashbrr instance: configured services, per-service health, and summary panels for many apps. Write tools cover settings management, download-queue deletes, Overseerr approvals, UI preferences, and the Plex auth PIN flow.
      34
      MIT