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: truenas-mcp

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