Skip to main content

MyAnimeList

Create and sync Plex collections from MyAnimeList user lists, rankings, and seasonal anime. homescreen-hero uses the MAL API to fetch anime data and matches it to your Plex library using the anime-lists mapping database.

Setup​

  1. Create a MAL API application at myanimelist.net/apiconfig
  2. Copy your Client ID
  3. Add it to your .env file:
HSH_MAL_CLIENT_ID=your-client-id
  1. If you didn't enable MAL in the Setup Wizard, enable it on the Lists page (or directly in config.yaml):
mal:
  enabled: true

Adding a Source​

MAL supports three modes: User Lists, Rankings, and Seasonal Anime.

User Lists​

Sync from any public MAL user's anime list, filtered by status (Watching, Completed, On Hold, Dropped, Plan to Watch).

  1. Go to the Integrations page in the dashboard
  2. Under MAL, select the User Lists tab
  3. Enter the MAL username and select a status filter
  4. Select which Plex library to sync to
  5. Adjust the collection name if needed
  6. Click Add

You can also paste a full MAL list URL (e.g., https://myanimelist.net/animelist/username).

Rankings​

Sync from MAL's ranking lists for curated discovery collections.

  1. Under MAL, select the Rankings tab
  2. Choose a ranking type:
    • All - Top anime overall
    • Airing - Currently airing top anime
    • Upcoming - Top upcoming anime
    • Most Popular - Most popular by member count
    • Most Favorited - Most favorited by users
  3. Select which Plex library to sync to
  4. Adjust the collection name if needed
  5. Click Add

Seasonal Anime​

Sync anime from a specific season and year.

  1. Under MAL, select the Seasonal tab
  2. Choose a year and season (Winter, Spring, Summer, Fall)
  3. Select which Plex library to sync to
  4. Adjust the collection name if needed
  5. Click Add

How Syncing Works​

When you sync a MAL source, homescreen-hero:

  1. Fetches all anime from the MAL list via the API (handles pagination automatically)
  2. Filters by format based on your target library type:
    • Show libraries: TV, OVA, ONA, Special
    • Movie libraries: Movie
  3. Matches each anime to your Plex library using a multi-step approach:
    • Looks up the MAL ID in the anime-lists mapping database to get TMDb, IMDb, and TVDB IDs
    • Tries matching by TMDb ID first (most reliable)
    • Falls back to IMDb ID, then TVDB ID
    • Last resort: title + year search
  4. Creates or updates the Plex collection with all matched items
  5. Removes stale items - if something is removed from the MAL source, it gets removed from the collection on the next sync
  6. Tracks missing items - any anime on the list that aren't in your Plex library are logged and viewable from the dashboard
note

The anime-lists mapping database is cached locally and refreshed every 24 hours. Both modern (tmdb://, imdb://, tvdb://) and legacy Plex agent GUIDs are supported for matching.

Missing Items​

After a sync, you can view which anime from the MAL source weren't found in your Plex library. Each missing item includes the title, year, media type, and MAL ID for easy lookup.