Skip to main content
Glama
qbittorrent-readonly-mcp

qbittorrent-readonly-mcp

by XiaotaoGuo

qBittorrent Read-only MCP

Это независимо поддерживаемый проект qBittorrent Read-only MCP, который оборачивает запросы к qBittorrent Web API в нативные stdio MCP-инструменты, чтобы AI-клиенты могли напрямую выполнять диагностику в реальном времени.

Модель безопасности

  • Поддерживается только stdio, сетевые порты не прослушиваются.

  • Адрес qBittorrent и API Key читаются только из окружения или внешнего секретного файла; параметры MCP-инструментов не могут переопределить цель подключения.

  • Клиенту разрешены только фиксированные GET endpoint'ы; нет универсальных инструментов request, URL или endpoint.

  • Не регистрируются пишущие инструменты для добавления, паузы, возобновления, проверки, удаления, перемещения, изменения трекера, изменения настроек.

  • Полный URL трекера, passkey, magnet, Cookie и данные аутентификации не попадают в результаты инструментов.

  • Сам qBittorrent API Key по-прежнему обладает полными правами Web API; режим только для чтения гарантируется двухуровневым allowlist'ом и тестами.

Этот MCP не выполняет рекурсивное сканирование файловой системы; его область ответственности ограничена запросами к qBittorrent в реальном времени.

Related MCP server: pve-mcp-server

Инструменты

  • get_health_summary: версия, скорости, статусы торрентов и сводка исключений.

  • list_torrents: фильтрация торрентов по статусу, категории, минимальному размеру, количеству дней без активности.

  • get_torrent_details: получение безопасных полей, файлов и hostname трекеров по префиксу Info Hash длиной не менее 8 символов.

  • list_problem_torrents: список торрентов с missingFiles, ошибками и незавершённых зависших торрентов.

  • 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

Настоящий read-only 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 поддерживает настройку локального STDIO MCP в .codex/config.toml для доверенных проектов. Ниже приведён пример конфигурации; здесь передаётся только путь к секретному файлу, 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-реализация использует официальный Python SDK Model Context Protocol.

Разработка

Основные уровни:

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

Любой новый endpoint должен сначала быть добавлен в READ_ONLY_ENDPOINTS, а также должны быть добавлены тесты для случаев «отказ не-белого списка» и «чувствительные поля не утекают».

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