Skip to main content
Glama
qbittorrent-readonly-mcp

qbittorrent-readonly-mcp

by XiaotaoGuo

qBittorrent Read-only MCP

This is an independently maintained read-only MCP project for qBittorrent. It wraps qBittorrent Web API queries as local stdio MCP tools, enabling AI clients to perform real-time diagnostics directly.

Security Model

  • Supports stdio only; does not listen on any network port.

  • The qBittorrent address and API Key are read only from the environment or an external secrets file; MCP tool arguments cannot override the connection target.

  • Clients are only allowed to use a fixed set of GET endpoints; there are no generic request, URL, or endpoint tools.

  • No write tools are registered for adding, pausing, resuming, verifying, deleting, moving, changing trackers, or changing settings.

  • Full tracker URLs, passkeys, magnet links, cookies, and authentication information never appear in tool results.

  • The qBittorrent API Key itself still has full Web API permissions; read-only behavior is guaranteed by the service's two-layer allowlist and tests.

This MCP does not perform recursive file system scans; its scope is limited to real-time qBittorrent queries.

Related MCP server: pve-mcp-server

Tools

  • get_health_summary: Version, speed, torrent status, and exception summary.

  • list_torrents: Filter torrents by status, category, minimum size, and days of inactivity.

  • get_torrent_details: Retrieve safe fields, files, and tracker hostnames by an Info Hash prefix of at least 8 characters.

  • list_problem_torrents: List torrents with missingFiles, errors, and stalled incomplete torrents.

  • analyze_largest_torrents: Analyze the Top N torrents by logical size.

Environment Requirements

  • Python 3.10+

  • uv

  • The following are expected to be present in a secrets file outside the project:

    • QBIT_URL

    • QBIT_API_KEY

By default, they are read from the process environment. Alternatively, you can pass only the path to the secrets file:

export QBIT_MCP_ENV_FILE="/path/to/secrets/nas-audit.env"

Do not copy the Key into this directory or into the Codex configuration.

Installation and Testing

cd /path/to/qbittorrent-readonly-mcp
uv sync
uv run pytest

Real read-only smoke test (outputs only tool names and redaction check results):

uv run python scripts/live_smoke.py \
  --env-file /path/to/secrets/nas-audit.env

Start locally:

QBIT_MCP_ENV_FILE="/path/to/secrets/nas-audit.env" \
  uv run qbittorrent-readonly-mcp

Once the service starts, it uses stdin/stdout to communicate via the MCP protocol; no ordinary interactive prompt is displayed.

Codex Configuration

Codex supports configuring a local STDIO MCP in a trusted project's .codex/config.toml. The following is an example configuration; only the secrets file path is passed here, and the API Key is not written into the configuration. The actual path should be maintained by the host project that uses this MCP:

[mcp_servers.qbittorrent_readonly]
command = "/path/to/qbittorrent-readonly-mcp/.venv/bin/qbittorrent-readonly-mcp"
args = []
cwd = "/path/to/qbittorrent-readonly-mcp"
enabled = true
required = false
startup_timeout_sec = 20
tool_timeout_sec = 60
default_tools_approval_mode = "auto"
enabled_tools = [
  "get_health_summary",
  "list_torrents",
  "get_torrent_details",
  "list_problem_torrents",
  "analyze_largest_torrents",
]

[mcp_servers.qbittorrent_readonly.env]
QBIT_MCP_ENV_FILE = "/path/to/secrets/nas-audit.env"

This repository does not store any Codex configuration or any credentials. Callers only need to reference this project's startup command and pass in the path to a secrets file located outside the project.

For Codex MCP configuration, refer to the OpenAI official documentation. The Python implementation uses the Model Context Protocol official Python SDK.

Development

Core layers:

MCP tools
  -> ReadOnlyQbitService(筛选、聚合、固定输出)
    -> QbitReadOnlyClient(固定 GET allowlist)
      -> qBittorrent Web API

Any new endpoint must first be added to READ_ONLY_ENDPOINTS, and tests must be added for “non-allowlist rejection” and “no leakage of sensitive fields”.

Available Tools

5 tools
analyze_largest_torrentsB
Read-onlyIdempotent

Return the largest torrents, optionally limited to a minimum inactivity age.

Inputs: limit, inactive_days. Returns: object

get_health_summaryA
Read-onlyIdempotent

Return versions, transfer speeds, task state counts, and read-only problem summary.

Inputs: no named parameters. Returns: object

get_torrent_detailsA
Read-onlyIdempotent

Get safe details for one torrent using an 8+ character hexadecimal Info Hash prefix.

Inputs: identifier (required). Returns: object

list_problem_torrentsA
Read-onlyIdempotent

List missing, errored, unknown, or incomplete stalled/stopped torrents.

Inputs: limit. Returns: object

list_torrentsC
Read-onlyIdempotent

List torrents using local filters; no filter value is sent as an arbitrary API endpoint.

Inputs: limit, state, category, min_size_gib, +1 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct monitoring concern: aggregate health, general torrent listing, per-torrent details, problem triage, and size/inactivity analysis. The two list-like tools are clearly differentiated by filtering to problem torrents versus all torrents.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (get_*, list_*, analyze_*). There are no mixed conventions or vague one-word identifiers.

    Tool Count5/5

    Five tools is a well-scoped set for a read-only qBittorrent monitoring server. Each tool provides a distinct capability without redundancy.

    Completeness4/5

    The surface covers the main read-only workflow: health summary, listing, details, problem identification, and size analysis. Minor gaps exist around lower-level details like trackers or peer lists, but agents can accomplish core monitoring without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server that monitors a Bitcoin Core full node via JSON-RPC, providing tools to check node status, network info, mempool, and peer information.
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      Read-only Proxmox VE MCP server providing 25 tools for VM, LXC, node, storage, and cluster inspection via stdio transport.
      25
      -
    • 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