qBittorrent Read-only MCP

Dies ist ein unabhängig gepflegtes qBittorrent-Read-only-MCP-Projekt, das die qBittorrent-Web-API-Abfragen als lokale stdio-MCP-Tools kapselt, damit KI-Clients direkte Echtzeitdiagnosen durchführen können.

Sicherheitsmodell

• Es wird nur stdio unterstützt; es wird kein Netzwerkport abgehört.

• Die qBittorrent-Adresse und der API-Schlüssel werden nur aus der Umgebung oder aus externen Geheimnisdateien gelesen; MCP-Toolparameter können das Verbindungsziel nicht überschreiben.

• Clients sind auf feste GET-Endpunkte beschränkt; es gibt keine allgemeinen Request-, URL- oder Endpunkt-Tools.

• Es werden keine Schreibwerkzeuge registriert, etwa zum Hinzufügen, Anhalten, Fortsetzen, Prüfen, Löschen, Verschieben, Ändern von Trackern oder Ändern von Einstellungen.

• Vollständige Tracker-URLs, Passkeys, Magnets, Cookies und Authentifizierungsinformationen gelangen nicht in die Tool-Ergebnisse.

• Der qBittorrent-API-Schlüssel selbst behält weiterhin volle Web-API-Berechtigungen; die Read-only-Eigenschaft wird durch die zweistufige Allowlist und die Tests dieses Dienstes gewährleistet.

Dieses MCP führt keine rekursiven Dateisystem-Scans durch; seine Aufgabe beschränkt sich auf Echtzeitabfragen an qBittorrent.

Related MCP server: truenas-mcp

Werkzeuge

• get_health_summary: Zusammenfassung von Version, Geschwindigkeit, Aufgabenstatus und Anomalien.

• list_torrents: Filtert Aufgaben nach Status, Kategorie, Mindestgröße und Tagen ohne Aktivität.

• get_torrent_details: Ruft anhand eines mindestens 8-stelligen Info-Hash-Präfixes sichere Felder, Dateien und Tracker-Hostnamen ab.

• list_problem_torrents: Listet missingFiles-, Fehler- und unvollständige, stillstehende Aufgaben auf.

• analyze_largest_torrents: Analysiert die Top-N-Aufgaben nach logischer Größe.

Umgebungsanforderungen

• Python 3.10+

• uv

• Bereits in einer geheimen Datei außerhalb des Projekts vorhanden:

  • QBIT_URL

  • QBIT_API_KEY

Standardmäßig werden sie aus der Prozessumgebung gelesen. Alternativ kann nur der Pfad zur Geheimnisdatei übergeben werden:

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

Kopieren Sie den Schlüssel nicht in dieses Verzeichnis oder in die Codex-Konfiguration.

Installation und Tests

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

Echter Read-only-Smoke-Test (gibt nur Tool-Namen und Ergebnisse der Entschärfungsprüfung aus):

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

Lokaler Start:

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

Nach dem Start des Dienstes wird das MCP-Protokoll über stdin/stdout übertragen; es wird keine normale interaktive Eingabeaufforderung angezeigt.

Codex-Konfiguration

Codex unterstützt die Konfiguration lokaler STDIO-MCP-Server in der .codex/config.toml eines vertrauenswürdigen Projekts. Im Folgenden finden Sie eine Beispielkonfiguration; hier wird nur der Pfad zur Geheimnisdatei übergeben, der API-Schlüssel wird nicht in die Konfiguration geschrieben. Der tatsächliche Pfad sollte vom Hostprojekt gepflegt werden, das dieses MCP verwendet:

[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"

Dieses Repository speichert weder Codex-Konfigurationen noch Anmeldedaten. Der Aufrufer muss lediglich das Startkommando dieses Projekts referenzieren und den Pfad zu einer Geheimnisdatei außerhalb des Projekts übergeben.

Zur Konfiguration von Codex-MCP siehe OpenAI-Dokumentation; die Python-Implementierung verwendet das offizielle Python-SDK des Model Context Protocol.

Entwicklung

Kernschichtung:

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

Jeder neue Endpunkt muss zuerst zu READ_ONLY_ENDPOINTS hinzugefügt werden, und es müssen Tests für „Ablehnung nicht auf der Whitelist“ und „Keine Weitergabe sensibler Felder“ ergänzt werden.