FlixBridge

Medienverwaltungs-MCP-Server
Verbinden Sie Ihren KI-Assistenten mit TV-Serien- und Filmverwaltungsdiensten

FlixBridge ist ein Model Context Protocol (MCP) Server, der KI-Assistenten mit Medienverwaltungsdiensten verbindet. Er bietet eine einheitliche Schnittstelle zur Überwachung von Downloads, zur Verwaltung von Bibliotheken und zur Automatisierung von Medien-Workflows.

✨ Hauptfunktionen

• 🎬 Multi-Service-Unterstützung - TV-Serien, Filme und Download-Clients

• 🔄 Echtzeit-Überwachung - Warteschlangenstatus, Systemzustand und Diagnosen

• 🤖 Intelligente Automatisierung - Automatische Fehlerbehebung bei hängenden Downloads und Workflow-Optimierung

• 🏢 Multi-Instanz-fähig - Qualitätsstufen, Inhaltstypen, Umgebungen

• 🔍 Intelligente Suche - Neue Inhalte finden und mit intelligenten Qualitätsprofilen hinzufügen

• 📊 Einheitliches Dashboard - Ein einziger Blick auf alle Ihre Dienste

• 🐛 Erweiterte Fehlersuche - Umfassende Protokollierung und Diagnosen

• ⚡ Hohe Leistung - Effizient, leichtgewichtig, TypeScript-fokussiert

Related MCP server: Trakt

📦 Installation

Über npm (Empfohlen)

# Install globally
npm install -g @thesammykins/flixbridge

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

📦 Auf npm ansehen

Aus dem Quellcode

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

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

🚀 Schnellstart

# 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

Oder mit Slug-basierter Konfiguration für mehrere Instanzen:

# 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

⚙️ Konfiguration

FlixBridge v0.3.x verwendet eine reine Umgebungskonfiguration mit Slug-basierter Erkennung. Es sind keine Konfigurationsdateien oder JSON-in-Env-Mappings erforderlich.

Slug-basierte Multi-Instanzen

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

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

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

• Präfix-Aliase werden ebenfalls akzeptiert: FLIX_BRIDGE_SONARR_<SLUG>_URL mit _KEY oder _API_KEY.

• Einzelinstanz-Präfix-Aliase werden ebenfalls akzeptiert, z. B. FLIX_BRIDGE_SABNZBD_URL mit FLIX_BRIDGE_SABNZBD_KEY.

Fallback-Variablen für Einzelinstanzen

• SONARR_URL

• SONARR_API_KEY

• RADARR_URL

• RADARR_API_KEY

• SABNZBD_URL

• SABNZBD_API_KEY

Beispiel für mehrere Instanzen

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

Hinweise:

• Dienstnamen lauten standardmäßig sonarr-<slug> / radarr-<slug> (Slug kleingeschrieben, _ → -).

• Wenn Sie <KIND>_<SLUG>_NAME festlegen, überschreibt dies den endgültigen Namen (stellen Sie sicher, dass er "sonarr"/"radarr" enthält, um die aktuelle Erkennung zu bestehen).

• Der Einzelinstanz-Fallback (SONARR_URL/RADARR_URL/SABNZBD_URL) funktioniert weiterhin für einfache Setups.

🛠️ Verfügbare Tools

⚠️ Wichtig: Rufen Sie immer zuerst list_services auf, um verfügbare Dienste zu entdecken, bevor Sie andere Tools verwenden.

Dienst-Erkennung

• list_services - Alle konfigurierten Dienste und Downloader entdecken

Kernoperationen

• system_status - Gesundheits- und Versionsinformationen

• queue_list - Download-Warteschlange mit Fortschrittsverfolgung

• queue_grab - Erzwingen eines erneuten Versuchs/Abrufs bestimmter Downloads

• queue_diagnostics - Analyse hängender Elemente; übergeben Sie autoFix:false für schreibgeschützte Prüfungen

• remove_content - Vorschau und Entfernen von Elementen aus der Warteschlange, Bibliothek oder dem Downloader mit Bestätigung

• root_folders - Speicherorte und freier Speicherplatz

Medienverwaltung

• search - Neue Serien/Filme zum Hinzufügen finden

• add_new - Medien mit intelligenten Qualitätsprofilen hinzufügen

• quality_profiles - Verfügbare Qualitätskonfigurationen auflisten

• history_detail - Download- und Importverlauf

• import_issues - Hängende Downloads und Importprobleme erkennen

Multi-Service-Tools

• all_services_diagnostics - Diagnosen über alle Instanzen hinweg ausführen

• download_status - Einheitlicher Status über Dienste und Downloader hinweg

• server_metrics - Lokale Betriebsmetriken und Gesundheitsstatus

Produktionssicherheit: queue_diagnostics und all_services_diagnostics sind standardmäßig auf autoFix:true eingestellt; übergeben Sie explizit autoFix:false für schreibgeschützte Produktions-Baselines. Verwenden Sie remove_content zuerst mit dryRun:true und führen Sie es erst nach Überprüfung der Vorschau mit dem zurückgegebenen confirmationToken aus.

🔧 MCP-Client-Einrichtung

Copy/Paste-Agent-Installations-Prompt

Verwenden Sie diesen Prompt mit Ihrem Coding-Agent, um FlixBridge zu installieren und eine fertige MCP-Konfiguration zurückzugeben:

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.

Wenn Sie ein Slug-basiertes Multi-Instanz-Setup verwenden, bitten Sie den Agent, SONARR_<SLUG>_*, RADARR_<SLUG>_* und SABNZBD_<SLUG>_* Variablen zu verwenden.

Claude Desktop

Fügen Sie dies zu claude_desktop_config.json hinzu:

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

Alternative: Globale Installation

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

Verwenden Sie es dann mit Claude Desktop, indem Sie Umgebungsvariablen bereitstellen (Standard oder via Mapping):

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

Einzelinstanz-Setup (Alternative)

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"

🐛 Fehlersuche

Aktivieren Sie die umfassende Debug-Protokollierung:

FLIX_BRIDGE_DEBUG=1 npm run dev

🧪 Testen

# Basic functionality test
npm run smoke

# Test with debug output  
FLIX_BRIDGE_DEBUG=1 npm run smoke

📚 Dokumentation

• Installation & Einrichtung - Anforderungen und Installation

• Konfigurationsanleitung - Alle Konfigurationsmethoden

• Nutzungsanleitung - MCP-Client-Einrichtung und Workflows

• API-Referenz - Vollständige Tool-Dokumentation

• Multi-Instanz-Einrichtung - Fortgeschrittene Multi-Instanz-Muster

• Fehlerbehebung - Häufige Probleme und Lösungen

• Architektur-Leitfaden - Technische Architektur für Entwickler

🤝 Mitwirken

1. Lesen Sie den Architektur-Leitfaden

2. Befolgen Sie die technischen Prinzipien in AGENTS.md

3. Behalten Sie den TypeScript-Strict-Modus bei

4. Fügen Sie Tests für neue Funktionen hinzu

5. Führen Sie npm run smoke aus, bevor Sie Änderungen einreichen

📄 Lizenz

MIT - siehe LICENSE Datei für Details

🆘 Hilfe benötigt?

1. Überprüfen Sie die Fehlerbehebungsanleitung

2. Diagnosen ausführen: npm run smoke

3. Debug-Modus aktivieren: FLIX_BRIDGE_DEBUG=1

4. Überprüfen Sie die Protokolle Ihrer Medienverwaltungsdienste

Mit ❤️ für die Home-Media-Automatisierungs-Community gemacht