Skip to main content

MDBList

Create and sync Plex collections from any MDBList list. Works just like the Trakt integration - paste a URL, pick a library, and homescreen-hero keeps your collection in sync.

Setup​

  1. Get your API key from mdblist.com/preferences
  2. Add it to your .env file:
HSH_MDBLIST_API_KEY=your-api-key
  1. If you didn't enable MDBList in the Setup Wizard, simply enable it on the Integrations page (or directly in config.yaml):
mdblist:
  enabled: true

Adding a List​

  1. Go to the Integrations page in the dashboard
  2. Click Add Source under MDBList
  3. Enter a name for the collection (this becomes the Plex collection name)
  4. Paste the MDBList URL (e.g., https://mdblist.com/lists/username/listname)
  5. Select which Plex library to sync to
  6. Click Save, then hit Sync to pull in the list

How Syncing Works​

When you sync an MDBList source, homescreen-hero:

  1. Fetches all items from the MDBList API (paginated, 100 items at a time)
  2. Matches each item to your Plex library using a multi-step approach:
    • First tries matching by TMDb ID (most reliable)
    • Falls back to IMDb ID
    • Then tries Trakt ID
    • Last resort: title + year search
  3. Creates or updates the Plex collection with all matched items
  4. Removes stale items - if something is removed from the MDBList list, it gets removed from the collection on the next sync
  5. Tracks missing items - any items on the list that aren't in your Plex library are logged and viewable from the dashboard
note

Syncing is non-destructive on errors. If the MDBList API returns no items (e.g., due to an outage or rate limiting), homescreen-hero won't wipe your existing collection.

Sync on Rotation​

MDBList sources can be synced automatically every time a rotation runs. This is controlled by the sync_all_on_rotation setting in your rotation config:

rotation:
  sync_all_on_rotation: true  # Sync all sources before each rotation

When disabled, only sources whose collection names match the selected rotation collections will be synced.

Missing Items​

After a sync, you can view which items from the MDBList weren't found in your Plex library. Each missing item includes its TMDb, IMDb, and Trakt IDs for easy lookup.

Automatic requesting of missing items via Radarr/Sonarr is planned for a future release.