qBittorrent Read-only MCP

这是一个独立维护的 qBittorrent 只读 MCP 项目，把 qBittorrent Web API 查询包装为本机 stdio MCP 工具，便于 AI 客户端直接做实时诊断。

安全模型

• 仅支持 stdio，不监听任何网络端口。

• qBittorrent 地址和 API Key 只从环境或外部秘密文件读取，MCP 工具参数不能覆盖连接目标。

• 客户端只允许固定 GET endpoint；没有通用 request、URL 或 endpoint 工具。

• 不注册添加、暂停、恢复、校验、删除、移动、改 tracker、改设置等写工具。

• 完整 tracker 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：按至少 8 位 Info Hash 前缀获取安全字段、文件和 tracker hostname。

• list_problem_torrents：列出 missingFiles、error 和未完成停滞任务。

• 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

真实只读 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 支持在可信项目的 .codex/config.toml 中配置本地 STDIO MCP。以下是示例配置；这里只传秘密文件路径，不把 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 实现使用 Model Context Protocol 官方 Python SDK。

开发

核心分层：

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

任何新 endpoint 都必须先加入 READ_ONLY_ENDPOINTS，并为“非白名单拒绝”和“敏感字段不泄漏”增加测试。