downloader-mcp

· claude-opus-4-8[1m] · 2026-07-07 · details

An MCP server for download clients — SABnzbd (usenet) and qBittorrent (torrents) — packaged as a Docker container. Companion to media-management MCPs like servarr-mcp.

Each client is optional: configure only the ones you actually run, and only those tools register.

Tools

SABnzbd (usenet)

qBittorrent (torrents)

Related MCP server: NZBGet MCP Server

Configuration

Each client requires its full config block to enable; partial config silently disables the client.

API keys / credentials are found in each app's settings:

• SABnzbd: Config → General → API Key

• qBittorrent: Tools → Options → Web UI (default user admin)

Note: SABnzbd and qBittorrent both default to port 8080. If you run both on the same host, remap one of them in its own config.

At least one client must be configured or the server exits with an error.

HTTP transport hardening (optional)

When running in HTTP mode (MCP_PORT set), you can enable bearer-token auth and DNS-rebinding protection with:

Both are opt-in and fail-soft: unset keeps prior behavior (unauthenticated, any Host accepted) so an existing deployment isn't broken by an upgrade, and the server logs a one-line startup warning recommending each one.

Recommended MCP_AUTH_TOKEN: a random secret, e.g. openssl rand -hex 32, passed by clients as Authorization: Bearer <token>.

Recommended MCP_ALLOWED_HOSTS: the host names/IPs clients actually use to reach the server — e.g. the NAS IP and host.docker.internal (MCP_ALLOWED_HOSTS=192.168.1.50:3003,host.docker.internal:3003).

Run with Docker

docker build -t downloader-mcp .
docker run -i --rm \
  -e SABNZBD_URL=http://192.168.1.50:8080 -e SABNZBD_API_KEY=... \
  -e QBITTORRENT_URL=http://192.168.1.50:8081 \
  -e QBITTORRENT_USERNAME=admin -e QBITTORRENT_PASSWORD=... \
  downloader-mcp

Published image

After each push to main, GitHub Actions builds and pushes a multi-arch image to GHCR:

ghcr.io/carldog/downloader-mcp:latest (linux/amd64 + linux/arm64)

Pull instead of building locally:

docker pull ghcr.io/carldog/downloader-mcp:latest
docker run -i --rm \
  -e SABNZBD_URL=... -e SABNZBD_API_KEY=... \
  ghcr.io/carldog/downloader-mcp:latest

Run with Docker Compose (HTTP, long-lived)

The compose file runs the server in HTTP mode (Streamable HTTP) for long-lived deployment via Portainer or Compose. It pulls the published image from ghcr.io/carldog/downloader-mcp:latest.

# Set whichever client credentials apply:
export SABNZBD_URL=http://192.168.1.50:8080; export SABNZBD_API_KEY=...
export QBITTORRENT_URL=http://192.168.1.50:8081
export QBITTORRENT_USERNAME=admin; export QBITTORRENT_PASSWORD=...
export HOST_PORT=3003  # optional, defaults to 3003

docker compose up

The MCP endpoint will be at http://<host>:${HOST_PORT}/mcp.

Deploy via Portainer (Stack from Git)

1. In Portainer, Stacks → Add Stack → Repository.

2. Repository URL: https://github.com/CarlDog/downloader-mcp

3. Compose path: docker-compose.yml

4. Environment variables: set whichever client credentials apply, plus optionally HOST_PORT.

5. Deploy. Healthcheck reaches green within ~10 seconds.

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "downloader": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SABNZBD_URL", "-e", "SABNZBD_API_KEY",
        "-e", "QBITTORRENT_URL",
        "-e", "QBITTORRENT_USERNAME", "-e", "QBITTORRENT_PASSWORD",
        "downloader-mcp"
      ],
      "env": {
        "SABNZBD_URL": "http://192.168.1.50:8080",
        "SABNZBD_API_KEY": "...",
        "QBITTORRENT_URL": "http://192.168.1.50:8081",
        "QBITTORRENT_USERNAME": "admin",
        "QBITTORRENT_PASSWORD": "..."
      }
    }
  }
}

Drop the -e/env entries for whichever client you don't run.

Local development

npm install
cp .env.example .env  # then edit
SABNZBD_URL=... SABNZBD_API_KEY=... npm run dev

Security

• Container runs as a non-root user (mcp).

• Credentials passed via env vars — never baked into the image.

• A .githooks/pre-commit runs gitleaks (secrets) and a PII pattern check (user-home paths, personal-domain emails). Activate it once per clone: git config core.hooksPath .githooks.