FlixBridge

Servidor MCP de gestión de medios
Conecta tu asistente de IA a servicios de gestión de películas y series de TV

FlixBridge es un servidor de Model Context Protocol (MCP) que conecta asistentes de IA con servicios de gestión de medios. Proporciona una interfaz unificada para supervisar descargas, gestionar bibliotecas y automatizar flujos de trabajo multimedia.

✨ Características principales

• 🎬 Soporte multiservicio - Series de TV, películas y clientes de descarga

• 🔄 Supervisión en tiempo real - Estado de la cola, salud del sistema y diagnósticos

• 🤖 Automatización inteligente - Corrección automática de descargas bloqueadas y optimización de flujos de trabajo

• 🏢 Preparado para múltiples instancias - Niveles de calidad, tipos de contenido, entornos

• 🔍 Búsqueda inteligente - Encuentra y añade nuevo contenido con perfiles de calidad inteligentes

• 📊 Panel unificado - Vista única de todos tus servicios

• 🐛 Depuración avanzada - Registro y diagnósticos exhaustivos

• ⚡ Alto rendimiento - Eficiente, ligero y basado en TypeScript

Related MCP server: Apifox MCP Server

📦 Instalación

Desde npm (Recomendado)

# Install globally
npm install -g @thesammykins/flixbridge

# Or install locally in your project
npm install @thesammykins/flixbridge

📦 Ver en npm

Desde el código fuente

# Clone the repository
git clone https://github.com/thesammykins/FlixBridge.git
cd FlixBridge

# Install dependencies and build
npm install && npm run build

🚀 Inicio rápido

# 1. Configure your services via environment variables
export SONARR_URL="http://localhost:8989"
export SONARR_API_KEY="your-sonarr-api-key"
export RADARR_URL="http://localhost:7878"
export RADARR_API_KEY="your-radarr-api-key"
# Optional downloader
export SABNZBD_URL="http://localhost:8080"
export SABNZBD_API_KEY="your-sabnzbd-api-key"

# 2. Build and run
npm run build
npm start

O con configuración basada en slugs para múltiples instancias:

# Multiple Sonarr instances
export SONARR_HD_URL="http://localhost:8989"
export SONARR_HD_API_KEY="your-hd-sonarr-key"
export SONARR_4K_URL="http://localhost:8990"
export SONARR_4K_API_KEY="your-4k-sonarr-key"

# Multiple Radarr instances  
export RADARR_MAIN_URL="http://localhost:7878"
export RADARR_MAIN_API_KEY="your-main-radarr-key"
export RADARR_UHD_URL="http://localhost:7879"
export RADARR_UHD_API_KEY="your-uhd-radarr-key"

npm start

⚙️ Configuración

FlixBridge v0.3.x utiliza configuración basada exclusivamente en variables de entorno con detección mediante slugs. No se requieren archivos de configuración ni mapeo de JSON en variables de entorno.

Múltiples instancias basadas en slugs

• Sonarr: SONARR_<SLUG>_URL, SONARR_<SLUG>_API_KEY, SONARR_<SLUG>_NAME (opcional)

• Radarr: RADARR_<SLUG>_URL, RADARR_<SLUG>_API_KEY, RADARR_<SLUG>_NAME (opcional)

• SABnzbd: SABNZBD_<SLUG>_URL, SABNZBD_<SLUG>_API_KEY, SABNZBD_<SLUG>_NAME (opcional)

• También se aceptan alias con prefijo: FLIX_BRIDGE_SONARR_<SLUG>_URL con _KEY o _API_KEY.

• También se aceptan alias con prefijo para una sola instancia, p. ej. FLIX_BRIDGE_SABNZBD_URL con FLIX_BRIDGE_SABNZBD_KEY.

Variables de respaldo para una sola instancia

• SONARR_URL

• SONARR_API_KEY

• RADARR_URL

• RADARR_API_KEY

• SABNZBD_URL

• SABNZBD_API_KEY

Ejemplo de múltiples instancias

# Sonarr
export SONARR_MAIN_URL="http://sonarr-main:8989"
export SONARR_MAIN_API_KEY="{{SONARR_MAIN_KEY}}"
export SONARR_4K_URL="http://sonarr-4k:8989"
export SONARR_4K_API_KEY="{{SONARR_4K_KEY}}"

# Radarr
export RADARR_MAIN_URL="http://radarr-main:7878"
export RADARR_MAIN_API_KEY="{{RADARR_MAIN_KEY}}"
export RADARR_UHD_URL="http://radarr-uhd:7878"
export RADARR_UHD_API_KEY="{{RADARR_UHD_KEY}}"

# SABnzbd (optional)
export SABNZBD_MAIN_URL="http://sab-main:8080"
export SABNZBD_MAIN_API_KEY="{{SAB_MAIN_KEY}}"

Notas:

• Los nombres de los servicios tienen como valor predeterminado sonarr-<slug> / radarr-<slug> (slug en minúsculas, _ → -).

• Si estableces <KIND>_<SLUG>_NAME, eso sobrescribe el nombre final (asegúrate de que contenga "sonarr"/"radarr" para pasar la detección actual).

• El respaldo para una sola instancia (SONARR_URL/RADARR_URL/SABNZBD_URL) sigue funcionando para configuraciones simples.

🛠️ Herramientas disponibles

⚠️ Importante: Llama siempre a list_services primero para descubrir los servicios disponibles antes de usar cualquier otra herramienta.

Descubrimiento de servicios

• list_services - Descubre todos los servicios y descargadores configurados

Operaciones principales

• system_status - Información de salud y versión

• queue_list - Cola de descargas con seguimiento de progreso

• queue_grab - Forzar reintento/captura de descargas específicas

• queue_diagnostics - Analizar elementos bloqueados; pasa autoFix:false para comprobaciones de solo lectura

• remove_content - Previsualizar y eliminar elementos de la cola, biblioteca o descargador con confirmación

• root_folders - Ubicaciones de almacenamiento y espacio libre

Gestión de medios

• search - Buscar nuevas series/películas para añadir

• add_new - Añadir medios con perfiles de calidad inteligentes

• quality_profiles - Listar configuraciones de calidad disponibles

• history_detail - Historial de descargas e importaciones

• import_issues - Detectar descargas bloqueadas y problemas de importación

Herramientas multiservicio

• all_services_diagnostics - Ejecutar diagnósticos en todas las instancias

• download_status - Estado unificado en todos los servicios y descargadores

• server_metrics - Métricas de operación local y estado de salud

Seguridad en producción: queue_diagnostics y all_services_diagnostics tienen autoFix:true por defecto; pasa explícitamente autoFix:false para líneas base de producción de solo lectura. Usa remove_content con dryRun:true primero y ejecuta solo con el confirmationToken devuelto después de comprobar la vista previa.

🔧 Configuración del cliente MCP

Prompt de instalación para copiar/pegar en el agente

Usa este prompt con tu agente de programación para instalar FlixBridge y obtener una configuración MCP lista para copiar y pegar:

Install and configure FlixBridge MCP for me.

Requirements:
1) Install package: @thesammykins/flixbridge
2) Generate MCP config for Claude Desktop using command "npx" and args ["@thesammykins/flixbridge"]
3) Include these env vars in the config with my values:
   - SONARR_URL
   - SONARR_API_KEY
   - RADARR_URL
   - RADARR_API_KEY
   - SABNZBD_URL (optional)
   - SABNZBD_API_KEY (optional)
4) Return only:
   - exact install command(s)
   - exact claude_desktop_config.json snippet
   - a 3-step verification checklist
5) After setup, remind me to call list_services first.

Si utilizas una configuración de múltiples instancias basada en slugs, pide al agente que utilice las variables SONARR_<SLUG>_*, RADARR_<SLUG>_* y SABNZBD_<SLUG>_*.

Claude Desktop

Añade a claude_desktop_config.json:

{
  "mcpServers": {
    "flixbridge": {
      "command": "npx",
      "args": ["@thesammykins/flixbridge"],
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key"
      }
    }
  }
}

Alternativa: Instalación global

# Install globally for easier usage
npm install -g @thesammykins/flixbridge

Luego úsalo con Claude Desktop proporcionando variables de entorno (estándar o mediante mapeo):

{
  "mcpServers": {
    "flixbridge": {
      "command": "flixbridge",
      "env": {
        "SONARR_URL": "http://localhost:8989",
        "SONARR_API_KEY": "your-sonarr-api-key",
        "RADARR_URL": "http://localhost:7878",
        "RADARR_API_KEY": "your-radarr-api-key",
        "SABNZBD_URL": "http://localhost:8080",
        "SABNZBD_API_KEY": "your-sabnzbd-api-key"
      }
    }
  }
}

Configuración de una sola instancia (Alternativa)

export SONARR_URL="http://localhost:8989"
export SONARR_API_KEY="your-sonarr-api-key"
export RADARR_URL="http://localhost:7878" 
export RADARR_API_KEY="your-radarr-api-key"
export SABNZBD_URL="http://localhost:8080"
export SABNZBD_API_KEY="your-sabnzbd-api-key"

🐛 Depuración

Habilita el registro de depuración exhaustivo:

FLIX_BRIDGE_DEBUG=1 npm run dev

🧪 Pruebas

# Basic functionality test
npm run smoke

# Test with debug output  
FLIX_BRIDGE_DEBUG=1 npm run smoke

📚 Documentación

• Instalación y configuración - Requisitos e instalación

• Guía de configuración - Todos los métodos de configuración

• Guía de uso - Configuración del cliente MCP y flujos de trabajo

• Referencia de API - Documentación completa de herramientas

• Configuración de múltiples instancias - Patrones avanzados de múltiples instancias

• Solución de problemas - Problemas comunes y soluciones

• Guía de arquitectura - Arquitectura técnica para desarrolladores

🤝 Contribución

1. Lee la Guía de arquitectura

2. Sigue los principios de ingeniería en AGENTS.md

3. Mantén el modo estricto de TypeScript

4. Añade pruebas para nuevas funciones

5. Ejecuta npm run smoke antes de enviar

📄 Licencia

MIT - consulta el archivo LICENSE para más detalles

🆘 ¿Necesitas ayuda?

1. Consulta la guía de solución de problemas

2. Ejecuta diagnósticos: npm run smoke

3. Habilita el modo de depuración: FLIX_BRIDGE_DEBUG=1

4. Revisa los registros de tus servicios de gestión de medios

Hecho con ❤️ para la comunidad de automatización de medios domésticos