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

Инструменты

• 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, а также должны быть добавлены тесты для случаев «отказ не-белого списка» и «чувствительные поля не утекают».