sabnzbd-mcp

What is sabnzbd-mcp?

A Model Context Protocol (MCP) server for SABnzbd — a Usenet download manager. It gives any AI agent control over Usenet downloads. The server has zero external dependencies and is written in pure Python standard library.

How to use sabnzbd-mcp?

Install via pip: pip install sabnzbd-mcp. Set environment variables SABNZBD_URL and SABNZBD_API_KEY (or use a .env file or ~/.homelab.env). Run the command sabnzbd-mcp. It also runs in Docker. The server communicates over stdio using line-delimited JSON-RPC 2.0.

Key features of sabnzbd-mcp

• Zero dependencies — pure Python standard library, one file.
• 16 MCP tools for full queue, history, config, and category management.
• Asynchronous notifications conforming to MCP standards.
• Live resources and prompt templates for quick actions.
• Shared .env support from ~/.homelab.env.
• Works with any MCP client (Claude Desktop, Claude Code, Cursor, etc.).

Use cases of sabnzbd-mcp

• Monitor the SABnzbd download queue and server status via AI agent.
• Pause, resume, or set speed limits on active downloads.
• Add new NZB downloads by URL or uploaded file with category assignment.
• Browse download history and retry failed jobs.
• Combine with other MCP servers (e.g., Prowlarr, Sonarr, RomM) for full media automation.

FAQ from sabnzbd-mcp

What is sabnzbd-mcp and what does it do?

It is a Model Context Protocol server for SABnzbd that allows an AI agent to control Usenet downloads — view queues, add NZBs, manage history, and change server settings.

What dependencies does sabnzbd-mcp require?

None beyond the Python standard library. The server is a single self-contained file with zero external dependencies.

How do I configure sabnzbd-mcp?

Set the environment variables SABNZBD_URL (base URL of your SABnzbd instance) and SABNZBD_API_KEY (from Settings → General). Optionally, create a .env file in the current directory or a ~/.homelab.env file in your home directory. Configuration via environment variables is also supported.

Which MCP clients are supported?

Any MCP host works, including Claude Desktop, Claude Code, Codex, OpenCode, Cursor, and Windsurf. Example configuration files for several clients are provided in the README.

How does sabnzbd-mcp communicate with the AI agent and SABnzbd?

It communicates with the AI agent over stdin/stdout using line-delimited JSON-RPC 2.0 (no Content-Length framing). It talks to the SABnzbd server over HTTP using the SABnzbd API.