sabnzbd-mcp

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

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

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!).

Client Setup

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

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

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

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