qbittorrent-readonly-mcp
Provides read-only access to a qBittorrent instance, enabling health summaries, torrent listing and filtering, detailed torrent information, problem torrent identification, and analysis of the largest torrents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@qbittorrent-readonly-mcp What's the current health and any problem torrents?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
stdioonly; 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 withmissingFiles, errors, and stalled incomplete torrents.analyze_largest_torrents: Analyze the Top N torrents by logical size.
Environment Requirements
Python 3.10+
uvThe following are expected to be present in a secrets file outside the project:
QBIT_URLQBIT_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 pytestReal 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.envStart locally:
QBIT_MCP_ENV_FILE="/path/to/secrets/nas-audit.env" \
uv run qbittorrent-readonly-mcpOnce 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 APIAny 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 toolsanalyze_largest_torrentsBRead-onlyIdempotent
Return the largest torrents, optionally limited to a minimum inactivity age.
Inputs: limit, inactive_days. Returns: object
get_health_summaryARead-onlyIdempotent
Return versions, transfer speeds, task state counts, and read-only problem summary.
Inputs: no named parameters. Returns: object
get_torrent_detailsARead-onlyIdempotent
Get safe details for one torrent using an 8+ character hexadecimal Info Hash prefix.
Inputs: identifier (required). Returns: object
list_problem_torrentsARead-onlyIdempotent
List missing, errored, unknown, or incomplete stalled/stopped torrents.
Inputs: limit. Returns: object
list_torrentsCRead-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
Scored across 5 tools
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.
All tool names follow a consistent snake_case verb_noun pattern (get_*, list_*, analyze_*). There are no mixed conventions or vague one-word identifiers.
Five tools is a well-scoped set for a read-only qBittorrent monitoring server. Each tool provides a distinct capability without redundancy.
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
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Read-only DERO blockchain MCP: 33 tools (12 composites) incl. TELA discovery + bundled docs.
Read-only developer, date, finance, and text utilities. Authless remote MCP server by Clean.tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceRead-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
- FlicenseBqualityDmaintenanceRead-only Proxmox VE MCP server providing 25 tools for VM, LXC, node, storage, and cluster inspection via stdio transport.25-
- AlicenseBqualityCmaintenanceMCP 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.12MIT
- AlicenseAqualityCmaintenanceA read-only MCP server that exposes AI Disk Doctor Core's scan, model inventory, and history tools via local stdio, with no mutation or shell capabilities.4Apache 2.0