NZBGet Server

An MCP (Model Context Protocol) server for NZBGet that exposes NZBGet API functionality as MCP tools usable by LLM clients.

Control your Usenet downloads with natural language through Claude and other MCP-compatible clients.

Features

• 15 MCP tools for complete NZBGet control
• Queue management: list, add, pause, resume, delete downloads
• History tracking: view completed and failed downloads
• Speed control: set download rate limits
• Status monitoring: real-time server status, disk space, queue info
• Logging: access and write to NZBGet logs
• TypeScript implementation with JSON-RPC client
• Stdio transport compatible with Claude Desktop

Requirements

• Node.js 18+
• A running NZBGet instance with RPC enabled

Setup

1. Clone the repository and install dependencies:

git clone https://github.com/aserper/nzbget-mcp.git
cd nzbget-mcp
npm install

2. Build the project:

npm run build

3. Copy .env.example to .env and set your values:

cp .env.example .env

Edit .env:

NZBGET_HOST=localhost
NZBGET_PORT=6789
NZBGET_USERNAME=nzbget
NZBGET_PASSWORD=tegbzn6789
NZBGET_USE_HTTPS=false

Running the MCP Server

npm start

Or directly:

node dist/index.js

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:ui

Architecture

This MCP server uses a modular architecture:

• src/tools/*.ts - Individual tool implementations
• src/tools/index.ts - Tool registry and discovery
• src/utils/errors.ts - Error handling utilities
• src/__tests__/mocks/ - Test fixtures and mocks

All 15 tools are self-contained modules that register themselves on import.

Configuration

Variable	Description	Default
NZBGET_HOST	NZBGet hostname	localhost
NZBGET_PORT	NZBGet RPC port	6789
NZBGET_USERNAME	NZBGet username	-
NZBGET_PASSWORD	NZBGet password	-
NZBGET_USE_HTTPS	Use HTTPS	false

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or equivalent on other platforms):

{
  "mcpServers": {
    "nzbget": {
      "command": "node",
      "args": ["/path/to/nzbget-mcp/dist/index.js"],
      "env": {
        "NZBGET_HOST": "localhost",
        "NZBGET_PORT": "6789",
        "NZBGET_USERNAME": "nzbget",
        "NZBGET_PASSWORD": "tegbzn6789"
      }
    }
  }
}

Docker

Build Locally

docker build -t nzbget-mcp .

Run

docker run --rm -it \
  -e NZBGET_HOST="localhost" \
  -e NZBGET_PORT="6789" \
  -e NZBGET_USERNAME="nzbget" \
  -e NZBGET_PASSWORD="tegbzn6789" \
  nzbget-mcp

Exposed Tools

Status & Information

• nzbget_status - Get server status (speed, queue size, disk space)
• nzbget_version - Get NZBGet version
• nzbget_server_volumes - Get download statistics per server

Download Queue

• nzbget_list_groups - List all downloads in queue
• nzbget_append - Add NZB file to queue
• nzbget_edit_queue - Edit queue (pause, resume, delete, set priority)

History

• nzbget_history - View download history

Control

• nzbget_pause_download / nzbget_resume_download
• nzbget_pause_post / nzbget_resume_post
• nzbget_rate - Set download speed limit (KB/s)
• nzbget_scan - Scan for new NZB files

Logging

• nzbget_log - Get log entries
• nzbget_write_log - Write custom log message

Usage Examples

"Show me what's currently downloading"
"Pause the download queue"
"Set download speed to 5 MB/s"
"Add an NZB file to the queue"
"Show my recent download history"

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Lint
npm run lint

# Type check
npm run typecheck

License

MIT

Contributing

Contributions welcome! Feel free to open an issue or submit a PR.