Enhanced Channel Manager

A professional-grade web interface for managing IPTV configurations with Dispatcharr. Built with React + TypeScript and Python FastAPI.

ECM gives you full control over your IPTV setup: manage M3U accounts and EPG sources, create and organize channels with drag-and-drop, automate channel creation with a powerful rules engine, probe stream health, build FFmpeg commands visually, and monitor live streaming stats — all from a single interface.

Installation

Docker Compose (Recommended)

services:
  ecm:
    image: ghcr.io/motwakorb/enhancedchannelmanager:latest
    ports:
      - "6100:6100"   # HTTP (configurable via ECM_PORT)
      - "6143:6143"   # HTTPS (configurable via ECM_HTTPS_PORT)
    volumes:
      - ./config:/config
    environment:
      - PUID=1000
      - PGID=1000
      - ECM_PORT=6100
      - ECM_HTTPS_PORT=6143

That's it. Open http://localhost:6100 and the setup wizard will guide you through creating an admin account and connecting to Dispatcharr.

With MCP Server (Claude AI Integration)

To add the optional MCP server for managing ECM through Claude, add the MCP service to your compose file:

services:
  ecm:
    image: ghcr.io/motwakorb/enhancedchannelmanager:latest
    ports:
      - "6100:6100"
      - "6143:6143"
    volumes:
      - ./config:/config
    environment:
      - PUID=1000
      - PGID=1000

  ecm-mcp:
    image: ghcr.io/motwakorb/enhancedchannelmanager-mcp:latest
    ports:
      - "6101:6101"
    volumes:
      - ./config:/config:ro
    environment:
      - ECM_URL=http://ecm:6100
      - MCP_PORT=6101
    depends_on:
      ecm:
        condition: service_healthy

Or if you're building from source, use the MCP compose overlay:

docker compose -f docker-compose.yml -f docker-compose.mcp.yml up -d

See MCP Server (Claude Integration) for setup instructions.

User / Group Identifiers:

• PUID (default: 1000) — User ID the application runs as
• PGID (default: 1000) — Group ID the application runs as

Set these to match the owner of your bind-mounted volumes to avoid permission issues. Find your IDs with id your_user.

Port Configuration:

• ECM_PORT (default: 6100) — HTTP interface (always available as fallback)
• ECM_HTTPS_PORT (default: 6143) — HTTPS interface (when TLS is configured in Settings)

Volumes:

• /config — Persistent storage for database, settings, logos, TLS certificates, and backups

Backup & Restore

ECM supports full backup and restore of all configuration. You can create backups from Settings, or restore from a backup during the first-run setup wizard.

Development Setup

# Frontend
cd frontend && npm install && npm run dev

# Backend
cd backend && pip install -r requirements.txt && uvicorn main:app --reload

Features

Channel Management

Full CRUD for channels and groups with a split-pane layout. Drag-and-drop streams onto channels, reorder streams by priority, bulk-create channels from stream groups with smart name normalization (quality variants, country prefixes, timezone handling), and organize everything into numbered channel groups. Staged edit mode lets you queue changes locally and commit or discard them as a batch.

M3U Manager

Manage Standard M3U, XtreamCodes, and HD Homerun accounts. Link related accounts so group enable/disable changes cascade automatically. Track changes detected across M3U refreshes with filtering, search, and optional email digest notifications.

EPG Manager

Configure multiple XMLTV and Schedules Direct EPG sources with drag-and-drop priority ordering. Create dummy EPG entries for channels without guide data. Bulk EPG assignment uses country-aware matching, call sign scoring, and HD preference to automatically map EPG data to channels.

TV Guide

EPG grid view with now-playing highlights, date/time navigation, channel profile filtering, and click-to-edit channel metadata.

Auto-Creation Pipeline

A rules-based automation engine for channel creation, stream merging, and lifecycle management. Build complex conditions (stream name, group, quality, codec, normalized matching, etc.) with AND/OR logic, then define actions (create channel/group, merge streams, assign metadata, set variables, name transforms). Per-rule normalization group selection lets each rule apply specific normalization groups. Supports dry-run preview, execution rollback, YAML import/export, orphan reconciliation, and a diagnostic debug bundle for troubleshooting.

FFMPEG Builder

Visual interface for constructing FFmpeg commands with Simple (three-step IPTV wizard) and Advanced modes. Includes 8 built-in IPTV presets, hardware acceleration support (CUDA, QSV, VAAPI), annotated command preview with tooltips, saved profiles, and direct push to Dispatcharr as stream profiles.

Stream Health & Probing

Automated stream probing with configurable schedules, batch sizes, retry logic, and rate limit detection. Profile-aware probing distributes connections across M3U profiles. Results drive smart stream sorting by resolution, bitrate, framerate, video codec, and M3U priority with configurable ordering for deprioritized stream categories. Black screen detection identifies streams showing dark/blank content, and low FPS detection flags streams below a configurable threshold (5/10/15/20 FPS). Both are deprioritized in Smart Sort. A strikeout system tracks consecutive failures for bulk cleanup.

Logo Manager

Browse, search, upload, and assign logos to channels. Supports URL import and file upload to Dispatcharr with usage tracking and pagination.

Stats & Monitoring

Live dashboard showing active channels, M3U connection counts, per-channel FFmpeg metrics (speed, FPS, bitrate), and bandwidth charts. Enhanced analytics include unique viewer tracking with Dispatcharr user identification, per-channel bandwidth, popularity scoring with trend analysis, and watch history with user attribution.

Journal

Activity log tracking all changes to channels, EPG, and M3U accounts with filtering by category, action type, and time range.

Settings

Comprehensive configuration including Dispatcharr connection, channel defaults, stream name normalization (tag-based and rule-based engines), stream probing, scheduled tasks (EPG/M3U refresh, probing, cleanup), alert methods (Discord, Telegram, email), authentication (local + Dispatcharr SSO), user management, TLS certificates, VLC integration, appearance themes, and backup/restore.

Authentication

First-run setup wizard, local auth with bcrypt hashing, Dispatcharr SSO, account linking, email-based password reset, and CLI password reset for lockout recovery. JWT-based sessions with automatic token refresh.

Notification Center

In-app notification bell with history, active task pinning, and external alert methods (Discord webhooks, Telegram bots, SMTP email) with digest batching and source filtering.

MCP Server (Claude Integration)

ECM includes an MCP (Model Context Protocol) server that lets Claude manage your channels through natural language. Ask Claude to list channels, refresh M3U accounts, probe stream health, run auto-creation pipelines, find and merge duplicate channels, view stats, and more — 124 tools across 14 domains.

Setup

1. Generate an API key in ECM Settings > MCP Integration
2. Start the MCP container — add the ecm-mcp service to your compose file (see With MCP Server) and start it on port 6101
3. Connect Claude using one of the methods below (replace YOUR_ECM_HOST and YOUR_API_KEY):

Claude Desktop — add to your Claude Desktop config:

{
  "mcpServers": {
    "ecm": {
      "url": "http://YOUR_ECM_HOST:6101/sse?api_key=YOUR_API_KEY"
    }
  }
}

Claude Code — create a .mcp.json file in any project directory where you want ECM tools available:

{
  "mcpServers": {
    "ecm": {
      "type": "sse",
      "url": "http://YOUR_ECM_HOST:6101/sse?api_key=YOUR_API_KEY"
    }
  }
}

To connect:

1. Create the .mcp.json file above in your project root (replace YOUR_ECM_HOST and YOUR_API_KEY)
2. Start Claude Code in that directory — it auto-detects .mcp.json on launch
3. Run /mcp to reconnect if the MCP server restarts
4. Ask Claude to manage your channels — e.g. "list my channels", "create an auto-creation rule for sports", "probe all streams"

If running ECM locally, use localhost as your host. If the MCP container is on the same Docker network as Claude Code, use the container name (ecm-mcp).

Available Tools (124)

Three read-only MCP resources provide quick context without a tool call: ecm://stats/overview, ecm://channels/summary, and ecm://tasks/status.

CLI Utilities

Password Reset

# Interactive mode (lists users, prompts for password)
docker exec -it enhancedchannelmanager python /app/reset_password.py

# Non-interactive
docker exec enhancedchannelmanager python /app/reset_password.py -u admin -p 'NewPass123'

# Skip password strength validation
docker exec enhancedchannelmanager python /app/reset_password.py -u admin -p 'simple' --force

Search Streams

./scripts/search-stream.sh http://dispatcharr:9191 admin password "ESPN"

Technical Stack

API Reference

Interactive API docs are available at /api/docs (Swagger UI) and /api/redoc. See docs/api.md for the full endpoint reference.

Roadmap

Completed

• v0.15.1 — OWASP hardening (security headers, CORS, rate limiting, NIST password policy, log redaction, path validation)
• v0.15.0 — Server-side EPG matching, stream normalization, PUID/PGID support, low FPS detection, export/publish pipeline
• v0.14.0 — Dummy EPG profiles, auto-creation pipeline, normalization engine
• v0.13.0 — Backend modularization (20+ routers), auth system, task engine

v0.16.0 — MCP Server & Claude Integration (Current)

MCP server for natural language channel management via Claude. 124 tools across 14 domains, SSE transport with API key auth, separate Docker container, frontend settings UI with connection status. Per-rule normalization group selection, video codec as smart sort criterion, configurable deprioritized stream ordering, diagnostic debug bundles, user identification in watch history and stats, and settings persistence hardening.

v0.17.0 — Dashboard & Analytics

Enhanced dashboard with real-time stream monitoring, historical analytics, and customizable widgets.