qBittorrent Read-only MCP

Este es un proyecto MCP de solo lectura para qBittorrent mantenido de forma independiente, que envuelve las consultas de la Web API de qBittorrent en una herramienta MCP stdio local, para que los clientes de IA puedan hacer diagnósticos en tiempo real directamente.

Modelo de seguridad

• Solo admite stdio; no escucha ningún puerto de red.

• La dirección de qBittorrent y la API Key solo se leen del entorno o de un archivo de secretos externo; los parámetros de la herramienta MCP no pueden sobrescribir el destino de conexión.

• El cliente solo permite endpoints GET fijos; no hay herramientas genéricas de request, URL o endpoint.

• No registra herramientas de escritura como agregar, pausar, reanudar, verificar, eliminar, mover, cambiar tracker o cambiar configuración.

• Las URL completas de tracker, passkey, magnet, cookies e información de autenticación no aparecen en los resultados de las herramientas.

• La API Key de qBittorrent por sí misma conserva todos los permisos de la Web API; la naturaleza de solo lectura está garantizada por la allowlist de dos capas de este servicio y por las pruebas.

Este MCP no realiza escaneos recursivos del sistema de archivos; su responsabilidad se limita a las consultas en tiempo real de qBittorrent.

Related MCP server: truenas-mcp

Herramientas

• get_health_summary: resumen de versión, velocidad, estado de las tareas y anomalías.

• list_torrents: filtra tareas por estado, categoría, tamaño mínimo y días sin actividad.

• get_torrent_details: obtiene campos seguros, archivos y el hostname del tracker mediante un prefijo de Info Hash de al menos 8 caracteres.

• list_problem_torrents: enumera tareas con missingFiles, errores y tareas incompletas estancadas.

• analyze_largest_torrents: analiza las N tareas principales por tamaño lógico.

Requisitos del entorno

• Python 3.10+

• uv

• En el archivo de secretos externo al proyecto ya existen:

  • QBIT_URL

  • QBIT_API_KEY

Por defecto se leen desde el entorno del proceso. También se puede pasar solo la ruta del archivo de secretos:

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

No copies la Key en este directorio ni en la configuración de Codex.

Instalación y pruebas

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

Prueba de humo real de solo lectura (solo genera el nombre de la herramienta y los resultados de la verificación de desinfección):

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

Inicio local:

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

Una vez iniciado el servicio, el protocolo MCP se transmite mediante stdin/stdout; no se mostrará un símbolo de sistema interactivo normal.

Configuración de Codex

Codex permite configurar una MCP STDIO local en .codex/config.toml de un proyecto de confianza. A continuación se muestra un ejemplo de configuración; aquí solo se pasa la ruta del archivo de secretos, sin escribir la API Key en la configuración. La ruta real debe ser mantenida por el proyecto anfitrión que use esta 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"

Este repositorio no guarda la configuración de Codex ni ninguna credencial. Quien lo invoque solo necesita hacer referencia al comando de inicio de este proyecto y pasar la ruta del archivo de secretos que se encuentra fuera del proyecto.

Para la configuración de la MCP de Codex, consulte la documentación oficial de OpenAI; la implementación en Python utiliza el SDK oficial de Python de Model Context Protocol.

Desarrollo

Capas principales:

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

Cualquier endpoint nuevo debe añadirse primero a READ_ONLY_ENDPOINTS, y se deben agregar pruebas para el “rechazo por no estar en la lista blanca” y para la “no fuga de campos sensibles”.