qbittorrent-readonly-mcp
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_URLQBIT_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 toolsanalyze_largest_torrentsBRead-onlyIdempotent
Return the largest torrents, optionally limited to a minimum inactivity age.
Inputs: limit, inactive_days. Returns: object
get_health_summaryARead-onlyIdempotent
Return versions, transfer speeds, task state counts, and read-only problem summary.
Inputs: no named parameters. Returns: object
get_torrent_detailsARead-onlyIdempotent
Get safe details for one torrent using an 8+ character hexadecimal Info Hash prefix.
Inputs: identifier (required). Returns: object
list_problem_torrentsARead-onlyIdempotent
List missing, errored, unknown, or incomplete stalled/stopped torrents.
Inputs: limit. Returns: object
list_torrentsCRead-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
Scored across 5 tools
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.
All tool names follow a consistent snake_case verb_noun pattern (get_*, list_*, analyze_*). There are no mixed conventions or vague one-word identifiers.
Five tools is a well-scoped set for a read-only qBittorrent monitoring server. Each tool provides a distinct capability without redundancy.
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
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
Read-only DERO blockchain MCP: 33 tools (12 composites) incl. TELA discovery + bundled docs.
Read-only developer, date, finance, and text utilities. Authless remote MCP server by Clean.tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceRead-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
- FlicenseBqualityDmaintenanceRead-only Proxmox VE MCP server providing 25 tools for VM, LXC, node, storage, and cluster inspection via stdio transport.25-
- AlicenseBqualityCmaintenanceMCP 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.12MIT
- AlicenseAqualityCmaintenanceA read-only MCP server that exposes AI Disk Doctor Core's scan, model inventory, and history tools via local stdio, with no mutation or shell capabilities.4Apache 2.0