# SABnzbd MCP

An MCP (Model Context Protocol) server for [SABnzbd](https://sabnzbd.org/) — 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)

```bash
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

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

### Claude Desktop (stdio)

```json
{
  "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

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