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: 논리적 크기로 상위 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