SABnzbd MCP

SABnzbd MCP

An MCP (Model Context Protocol) server for SABnzbd — manage your Usenet downloader through Claude or any MCP-compatible client.

Features

• Queue management — view, pause, resume, delete, reorder and reprioritize downloads
• History — browse, search, retry and delete completed/failed downloads
• Add downloads — add NZBs by URL with optional category, priority and script
• Speed control — set download speed limits on the fly
• Status & info — server status, version, warnings, categories and scripts
• Two transports — stdio (Claude Desktop) or HTTP (remote clients)

Tools

| Tool | Description | |------|-------------| | get_status | Full server status (speed, disk space, queue summary) | | get_version | SABnzbd version | | get_warnings | Current warnings and log messages | | get_categories | All configured categories | | get_scripts | All configured post-processing scripts | | get_queue | Download queue with pagination | | pause_queue | Pause all downloads | | resume_queue | Resume all downloads | | pause_post_processing | Pause post-processing | | resume_post_processing | Resume post-processing | | set_speed_limit | Set download speed limit | | delete_from_queue | Delete items from the queue | | set_priority | Set download priority | | change_category | Change category of a queue item | | move_in_queue | Move item to a specific queue position | | add_nzb_url | Add NZB by URL | | get_history | Download history with search and filtering | | retry_download | Retry a failed download | | retry_all_failed | Retry all failed downloads | | delete_history | Delete history items | | purge_history | Purge all history |

Quick start

Docker (HTTP mode)

docker run -d \
  -e SABNZBD_URL=http://your-sabnzbd:8080 \
  -e SABNZBD_API_KEY=your_api_key \
  -e MCP_TRANSPORT=http \
  -p 3001:3001 \
  ghcr.io/ltmarx/sabnzbd-mcp:latest

Docker Compose

cp .env.example .env
# edit .env with your SABnzbd URL and API key
docker compose --profile http up -d

Claude Desktop (stdio)

{
  "mcpServers": {
    "sabnzbd": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "SABNZBD_URL=http://your-sabnzbd:8080",
        "-e", "SABNZBD_API_KEY=your_api_key",
        "ghcr.io/ltmarx/sabnzbd-mcp:latest"
      ]
    }
  }
}

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | SABNZBD_URL | http://localhost:8080 | SABnzbd base URL | | SABNZBD_API_KEY | (required) | SABnzbd API key (Settings → General → API Key) | | MCP_TRANSPORT | stdio | Transport mode: stdio or http | | MCP_PORT | 3001 | HTTP port (only used when MCP_TRANSPORT=http) | | MCP_HOST | 0.0.0.0 | HTTP bind host (only used when MCP_TRANSPORT=http) |

Health check

In HTTP mode the server exposes GET /health, which also verifies connectivity to SABnzbd:

• 200 { "status": "ok", "sabnzbd": "reachable" } — server up and SABnzbd responding
• 503 { "status": "error", "sabnzbd": "unreachable" } — server up but SABnzbd not reachable

The Docker image and docker-compose.yml both wire this into a container HEALTHCHECK for the HTTP service (checked every 30s). stdio mode has no persistent server, so no health check applies there.

Development

npm install
cp .env.example .env
# edit .env
npm run dev