FlixBridge

Media Management MCP Server
Connect your AI assistant to TV shows and movie management services

FlixBridge is a Model Context Protocol (MCP) server that bridges AI assistants with media management services. It provides a unified interface for monitoring downloads, managing libraries, and automating media workflows.

✨ Key Features

🎬 Multi-Service Support - TV shows, movies, and download clients
🔄 Real-Time Monitoring - Queue status, system health, and diagnostics
🤖 Smart Automation - Auto-fix stuck downloads and optimize workflows
🏢 Multi-Instance Ready - Quality tiers, content types, environments
🔍 Intelligent Search - Find and add new content with smart quality profiles
📊 Unified Dashboard - Single view across all your services
🐛 Advanced Debugging - Comprehensive logging and diagnostics
⚡ High Performance - Efficient, lightweight, TypeScript-first

📦 Installation

From npm (Recommended)

# Install globally
npm install -g @thesammykins/flixbridge

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

📦 View on npm

From Source

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

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

🚀 Quick Start

# 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

Or with slug-based configuration for multiple instances:

# 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

⚙️ Configuration

FlixBridge v0.3.x uses environment-only configuration with slug-based discovery. No config files and no JSON-in-env mapping required.

Slug-based multiple instances

Sonarr: SONARR_<SLUG>_URL, SONARR_<SLUG>_API_KEY, optional SONARR_<SLUG>_NAME
Radarr: RADARR_<SLUG>_URL, RADARR_<SLUG>_API_KEY, optional RADARR_<SLUG>_NAME
SABnzbd: SABNZBD_<SLUG>_URL, SABNZBD_<SLUG>_API_KEY, optional SABNZBD_<SLUG>_NAME

Multi-Instance Example

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

Notes:

Service names default to sonarr-<slug> / radarr-<slug> (slug lowercased, _ → -).
If you set <KIND>_<SLUG>_NAME, that overrides the final name (ensure it contains "sonarr"/"radarr" to pass current detection).
Single-instance fallback (SONARR_URL/RADARR_URL/SABNZBD_URL) still works for simple setups.

🛠️ Available Tools

⚠️ Important: Always call list_services first to discover available services before using any other tools.

Service Discovery

list_services - Discover all configured services and downloaders

Core Operations

system_status - Health and version information
queue_list - Download queue with progress tracking
queue_grab - Force retry/grab specific downloads
queue_diagnostics - Auto-detect and fix stuck items
root_folders - Storage locations and free space

Media Management

search - Find new series/movies to add
add_new - Add media with intelligent quality profiles
quality_profiles - List available quality configurations
history_detail - Download and import history
import_issues - Detect stuck downloads and import problems

Multi-Service Tools

all_services_diagnostics - Run diagnostics across all instances
download_status - Unified status across services and downloaders

🔧 MCP Client Setup

Claude Desktop

Add to 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"
      }
    }
  }
}

Alternative: Global Installation

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

Then use with Claude Desktop by providing environment variables (standard or 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"
      }
    }
  }
}

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

🐛 Debugging

Enable comprehensive debug logging:

FLIX_BRIDGE_DEBUG=1 npm run dev

🧪 Testing

# Basic functionality test
npm run smoke

# Test with debug output  
FLIX_BRIDGE_DEBUG=1 npm run smoke

📚 Documentation

Installation & Setup - Requirements and installation
Configuration Guide - All configuration methods
Usage Guide - MCP client setup and workflows
API Reference - Complete tool documentation
Multi-Instance Setup - Advanced multi-instance patterns
Troubleshooting - Common issues and solutions
Architecture Guide - Technical architecture for developers

🤝 Contributing

Read the Architecture Guide
Follow engineering principles in AGENTS.md
Maintain TypeScript strict mode
Add tests for new features
Run npm run smoke before submitting

📄 License

MIT - see LICENSE file for details

🆘 Need Help?

Check the troubleshooting guide
Run diagnostics: npm run smoke
Enable debug mode: FLIX_BRIDGE_DEBUG=1
Review logs from your media management services

Made with ❤️ for the home media automation community