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.
⚠️ 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
- 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
- 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
🤝 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