SABnzbd MCP Server

[]()
[]()

[]()

<p align="center">

</p>

A Model Context Protocol server for SABnzbd — zero external dependencies. Give any AI agent control over Usenet downloads.

<p align="center">


</p>

pip install sabnzbd-mcp
export SABNZBD_URL="http://localhost:8080"
export SABNZBD_API_KEY="your-key"
sabnzbd-mcp

Features

- No dependencies — pure Python standard library. One file, zero installs beyond the package itself.
- 16 tools — full queue, history, config, category, priority, and queue position management.
- Asynchronous Notifications — conforming to MCP standards (sends notifications/message log events with severity levels).
- Resources & Prompts — exposes active download queues, history, status, and categories as live JSON resources, and provides interactive prompt templates for quick actions.
- Shared .env Support — seamlessly loads from ~/.homelab.env for unified configuration.
- Any client — Claude Desktop, Claude Code, Codex, OpenCode, Cursor, Windsurf, or any MCP host.
- Minimal — single file, zero deps. Easy to audit, extend, or fork.

Tools

| Category | Tool | Parameters | Description |
|---|---|---|---|
| Read | sab_queue | start (int), limit (int), search (str), category (str) | View download queue with pagination and search filtering |
| | sab_history | start (int), limit (int), search (str), category (str) | Browse history with pagination and search filtering |
| | sab_status | — | Server health — speed limits, disk space, directories |
| | sab_categories | — | List configured download categories |
| | sab_get_config | — | Get server configuration parameters |
| Control | sab_pause | nzo_id (str, optional) | Pause active downloads (or a specific job ID) |
| | sab_resume | nzo_id (str, optional) | Resume paused downloads (or a specific job ID) |
| | sab_set_speedlimit | value (str), mode (str) | Set global speed limit (percentage or absolute) |
| Add | sab_add_url | url (str), category (str) | Add an NZB by URL (with optional category) |
| | sab_add_nzb_file | content (str), filename (str), category (str) | Upload an NZB as base64-encoded content |
| Queue | sab_queue_delete | nzo_id (str), del_files (bool) | Remove download from queue, optionally deleting files |
| | sab_change_priority | nzo_id (str), priority (str) | Change priority (low/normal/high/force) of a queued download |
| | sab_set_category | nzo_id (str), category (str) | Change the category of a queued download |
| | sab_change_position | nzo_id (str), position (int) | Move a queued download to a different index position |
| History | sab_retry | nzo_id (str, optional) | Retry failed downloads (by NZO ID or all) |
| | sab_history_delete | nzo_id (str), del_files (bool) | Remove item from history, optionally deleting downloaded files |

Resources

The server exposes standard MCP resources that let clients inspect the state of your SABnzbd server directly as files/JSON documents:

- sabnzbd://queue — Live download queue JSON.
- sabnzbd://history — Complete download history JSON.
- sabnzbd://status — Detailed server status, free space, and directories.
- sabnzbd://categories — List of configured sorting categories.
- sabnzbd://config — Server configuration (with sensitive credentials automatically masked).

Prompts

We provide prompt templates to jump-start agent workflows:

1. sabnzbd_summary: Asks the agent to compile a comprehensive status report of the SABnzbd server health, queue, and recent history.
2. sabnzbd_download_nzb: Prompts the agent to download a Usenet NZB from a URL and monitors its status in the queue.

Configuration

You can provide configuration via environment variables, or by creating a .env file in the current directory, or a ~/.homelab.env file in your home directory (perfect for centralized toolchain configuration!).

| Variable | Required | Default | Description |
|---|---|---|---|
| SABNZBD_URL | Yes | http://localhost:8080 | Base URL of your SABnzbd instance |
| SABNZBD_API_KEY | Yes | — | API Key from Settings → General |
| SABNZBD_SSL_VERIFY | No | true | Set to false to disable SSL verification (for self-signed certs) |
| SABNZBD_POLL_INTERVAL | No | 15 | Seconds between background polling for completion notifications |

Client Setup

<details>
<summary><b>Claude Desktop</b></summary>

{
  "mcpServers": {
    "sabnzbd": {
      "command": "sabnzbd-mcp",
      "env": {
        "SABNZBD_URL": "http://localhost:8080",
        "SABNZBD_API_KEY": "your-api-key"
      }
    }
  }
}

<details>
<summary><b>Claude Code / Codex</b></summary>

claude mcp add sabnzbd -- sabnzbd-mcp \
  -e SABNZBD_URL="http://localhost:8080" \
  -e SABNZBD_API_KEY="your-api-key"

<details>
<summary><b>OpenCode</b></summary>

"sabnzbd": {
  "type": "local",
  "command": ["sabnzbd-mcp"],
  "env": {
    "SABNZBD_URL": "http://localhost:8080",
    "SABNZBD_API_KEY": "your-api-key"
  },
  "enabled": true
}

<details>
<summary><b>Cursor</b></summary>

Add to .cursor/mcp.json:

{

  "mcpServers": {

    "sabnzbd": {

      "command": "sabnzbd-mcp",

      "env": {

        "SABNZBD_URL": "http://localhost:8080",

        "SABNZBD_API_KEY": "your-api-key"

      }

    }

  }

}

Example Prompts

Once connected, your agent can respond to:

> "What's downloading right now?" → sab_queue

> "Pause all downloads until tomorrow" → sab_pause

> "Add this NZB to the games category" → sab_add_url

> "Show me what finished yesterday" → sab_history

> "How much disk space is left on the server?" → sab_status

Automation Pipeline

Combine with other MCP servers for end-to-end media automation:

Prowlarr (mcparr) → search indexers
  → qBittorrent / SABnzbd → download
    → Retroarr / Sonarr → sort & import
      → RomM → scan library

See docs/recipes/ for full pipeline examples.

Architecture

┌──────────────┐    stdin/stdout     ┌──────────────┐    HTTP     ┌───────────┐
│  AI Agent    │ ◄─────────────────► │  sabnzbd-mcp │ ◄─────────► │ SABnzbd   │
│  (Claude,    │    JSON-RPC 2.0     │  (Python)    │             │ (your     │
│   Codex...)  │                     │  stdlib only │             │  server)  │
└──────────────┘                     └──────────────┘             └───────────┘

The server is a single self-contained Python file (src/sabnzbd_mcp/server.py) with no dependencies beyond the standard library. It communicates over stdio using line-delimited JSON-RPC 2.0 — no Content-Length framing required.

Docker

You can easily run this MCP server via Docker alongside your other Arr apps.

Standard IO via Docker Run:

docker build -t sabnzbd-mcp .

docker run -i --rm \

  --env-file ~/.homelab.env \

  sabnzbd-mcp

Network Mode via Docker Compose (using socat):
See the included docker-compose.yml to deploy the MCP server so it listens on a TCP port, which Claude Desktop can connect to over your local network!

Development

git clone https://github.com/zz-plant/sabnzbd-mcp.git
cd sabnzbd-mcp
pip install -e ".[dev]"
ruff check src/
python -m pytest tests/

Contributing

See CONTRIBUTING.md. One PR per tool. Tests required.

License

MIT

---

Ecosystem

More open-source projects from zz-plant:

- Stims — Browser music visualizer inspired by MilkDrop
- Refract — Open infrastructure for agent-readable knowledge change
- neckass — Privacy-first headline generator with on-device AI
- ethotechnics.org — Essays on ethical technology and human-centered design