Servidor MCP de NZBGet

Un servidor MCP (Model Context Protocol) para NZBGet que expone la funcionalidad de la API de NZBGet como herramientas MCP utilizables por clientes LLM.

Controla tus descargas de Usenet con lenguaje natural a través de Claude y otros clientes compatibles con MCP.

Características

• 15 herramientas MCP para un control total de NZBGet

• Gestión de colas: listar, añadir, pausar, reanudar, eliminar descargas

• Seguimiento del historial: ver descargas completadas y fallidas

• Control de velocidad: establecer límites de tasa de descarga

• Supervisión de estado: estado del servidor en tiempo real, espacio en disco, información de la cola

• Registro: acceder y escribir en los registros de NZBGet

• Implementación en TypeScript con cliente JSON-RPC

• Transporte Stdio compatible con Claude Desktop

Requisitos

• Node.js 18+

• Una instancia de NZBGet en ejecución con RPC habilitado

Configuración

1. Clona el repositorio e instala las dependencias:

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

2. Compila el proyecto:

npm run build

3. Copia .env.example a .env y establece tus valores:

cp .env.example .env

Edita .env:

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

Ejecución del servidor MCP

npm start

O directamente:

node dist/index.js

Pruebas

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:ui

Arquitectura

Este servidor MCP utiliza una arquitectura modular:

• src/tools/*.ts - Implementaciones de herramientas individuales

• src/tools/index.ts - Registro y descubrimiento de herramientas

• src/utils/errors.ts - Utilidades de manejo de errores

• src/__tests__/mocks/ - Fixtures y mocks de prueba

Las 15 herramientas son módulos autónomos que se registran a sí mismos al importarse.

Configuración

Configuración de Claude Desktop

Añádelo a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS, o equivalente en otras plataformas):

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

Compilar localmente

docker build -t nzbget-mcp .

Ejecutar

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

Herramientas expuestas

Estado e información

• nzbget_status - Obtener el estado del servidor (velocidad, tamaño de cola, espacio en disco)

• nzbget_version - Obtener la versión de NZBGet

• nzbget_server_volumes - Obtener estadísticas de descarga por servidor

Cola de descarga

• nzbget_list_groups - Listar todas las descargas en la cola

• nzbget_append - Añadir archivo NZB a la cola

• nzbget_edit_queue - Editar cola (pausar, reanudar, eliminar, establecer prioridad)

Historial

• nzbget_history - Ver historial de descargas

Control

• nzbget_pause_download / nzbget_resume_download

• nzbget_pause_post / nzbget_resume_post

• nzbget_rate - Establecer límite de velocidad de descarga (KB/s)

• nzbget_scan - Escanear en busca de nuevos archivos NZB

Registro

• nzbget_log - Obtener entradas de registro

• nzbget_write_log - Escribir mensaje de registro personalizado

Ejemplos de uso

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

Desarrollo

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Lint
npm run lint

# Type check
npm run typecheck

Licencia

MIT

Contribución

¡Las contribuciones son bienvenidas! Siéntete libre de abrir un issue o enviar un PR.