qBittorrent Read-only MCP

これは独立にメンテナンスされている qBittorrent 読み取り専用 MCP プロジェクトで、qBittorrent Web API のクエリをローカルの stdio MCP ツールとしてラップし、AI クライアントが直接リアルタイム診断できるようにするものです。

安全モデル

• stdio のみに対応し、ネットワークポートを一切リッスンしません。

• qBittorrent のアドレスと API Key は環境変数または外部のシークレットファイルからのみ読み取られ、MCP ツールの引数で接続先を上書きすることはできません。

• クライアントは固定の GET endpoint のみ許可されます。汎用の request・URL・endpoint ツールはありません。

• 追加、一時停止、再開、チェック、削除、移動、tracker 変更、設定変更などの書き込みツールは登録されません。

• 完全な tracker URL、passkey、magnet、Cookie、認証情報はツールの結果に含まれません。

• qBittorrent API Key 自体は完全な Web API 権限を持っています。読み取り専用性は、本サービスの2層の allowlist とテストによって保証されます。

本 MCP はファイルシステムの再帰スキャンを実行せず、役割は qBittorrent のリアルタイムクエリに限定されます。

Related MCP server: truenas-mcp

ツール

• get_health_summary: バージョン、速度、タスク状態、異常のサマリー。

• list_torrents: 状態、カテゴリ、最小サイズ、非アクティブ日数でタスクをフィルタリング。

• get_torrent_details: 最低8桁の Info Hash プレフィックスで、安全なフィールド、ファイル、tracker ホスト名を取得。

• list_problem_torrents: missingFiles、error、および完了していない停滞タスクを一覧表示。

• analyze_largest_torrents: 論理サイズで Top N タスクを分析。

環境要件

• Python 3.10+

• uv

• プロジェクト外部のシークレットファイルに以下が含まれている:

  • QBIT_URL

  • QBIT_API_KEY

デフォルトではプロセス環境から読み取ります。シークレットファイルのパスのみを渡すこともできます:

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

Key をこのディレクトリや Codex 設定にコピーしないでください。

インストールとテスト

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

実際の読み取り専用 smoke test（ツール名とマスキング確認結果のみを出力）:

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

ローカル起動:

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

サービス起動後は stdin/stdout で MCP プロトコルを転送するため、通常の対話プロンプトは表示されません。

Codex 設定

Codex は信頼できるプロジェクトの .codex/config.toml でローカル STDIO MCP を設定できます。以下は設定例です。ここではシークレットファイルのパスのみを渡し、API Key を設定に書き込むことはしません。実際のパスは、この 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"

このリポジトリは Codex 設定も資格情報も保存しません。呼び出し側はこのプロジェクトの起動コマンドを参照し、プロジェクト外部のシークレットファイルパスを渡すだけで十分です。

Codex MCP の設定方法は OpenAI公式ドキュメント を参照し、Python 実装は Model Context Protocol 公式 Python SDK を使用しています。

開発

コアのレイヤリング:

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

新しい endpoint は必ず最初に READ_ONLY_ENDPOINTS に追加し、「非ホワイトリスト拒否」と「機密フィールドの漏洩なし」のテストを追加する必要があります。