PlexyTrack

<p align="center"> <img src="static/logo2.png" alt="PlexyTrack Logo" width="200" /> </p>

This project synchronizes your Plex library with Trakt or Simkl. Besides watched history it can optionally add items to your Trakt collection, sync ratings and watchlists, and now mirrors Trakt lists you like as Plex collections. Collections created in Plex will in turn appear as Trakt lists. A small Flask web interface lets you choose which features to enable and configure the sync interval. Items that are manually marked as watched in Plex are detected as well. The interface also includes a tool for creating backups of your history, watchlist and ratings. The recommended sync interval is at least 60 minutes. Shorter intervals generally do not provide any benefit, and you can even synchronize once every 24 hours to reduce the load on your server and the API.

Features

• Bidirectional sync of watched history between Plex and Trakt or Simkl
• Optional synchronization of ratings, collections, liked lists and watchlists (ratings supported for both Trakt and Simkl; Simkl accepts movies and shows only)
• Live Sync mode to trigger updates immediately from Plex webhooks
• Simple backup and restore of all your Trakt data from the web interface
• Intuitive UI for configuration and user selection

CONTENTS

• Disclaimer
• Requirements
• Collections and watchlists
• Backup and restore
• Live sync
• Getting a Plex token
• Getting Trakt API credentials
• Running on Unraid
• Running with Docker Compose
• Screenshots

Disclaimer

This application is currently in testing and is provided as is. I take no responsibility for any data loss that may occur when using it. Before you begin, you should use the backup tool to export your history, watchlist and ratings so they can be restored easily from the UI.

Requirements

The application expects the following API credentials:

Plex Authentication

• PLEX_BASEURL – URL of your Plex server, e.g. http://localhost:32400. If no scheme is provided, http:// is assumed.
• PLEX_TOKEN – your Plex authentication token.

When syncing, the application reuses the token generated from the web login of the selected user. The server connection always uses the IP provided in PLEX_BASEURL. The legacy PLEX_TOKEN/PLEX_BASEURL method is only attempted if no session token is available.

Optional environment variables

These are only needed for the initial web authentication; the sync itself uses the generated token and does not store these credentials.

• PLEX_EMAIL – your Plex account email address.
• PLEX_PASSWORD – your Plex account password.
• PLEX_2FA_CODE – optional 2FA code (required if 2FA is enabled on your Plex account).
• PLEX_SERVER_NAME – optional specific server name (if you have multiple servers).

Sync Services

• TRAKT_CLIENT_ID – client ID for your Trakt application (optional if only using Simkl).
• TRAKT_CLIENT_SECRET – client secret from your Trakt application (optional if only using Simkl).
• SIMKL_CLIENT_ID – client ID for your Simkl application (optional if only using Trakt).
• SIMKL_CLIENT_SECRET – client secret for your Simkl application (optional if only using Trakt).
• TRAKT_REDIRECT_URI – optional custom OAuth redirect URI for Trakt. If not set, the application uses the address from which the UI is accessed (for example, http://localhost:5030/oauth/trakt).
• SIMKL_REDIRECT_URI – optional custom OAuth redirect URI for Simkl. When unset, the address of the current UI is used automatically.
• TZ – timezone for log timestamps, defaults to Europe/Madrid.

You must set the Plex base URL, plex token (as fallback) and at least one pair of Trakt or Simkl credentials. Leave the variables for the service you are not using unset.

You do not need to provide a Trakt access token or refresh token. The web interface will guide you through authorizing the app and will store the tokens for you.

Authorization codes will appear in the OAuth tab and can then be entered from the Config. tab, which shows whether each service is already configured. If you want to remove saved tokens, the Config page also provides Clear Config buttons for both Trakt and Simkl.

All sync options and the chosen Plex user are saved to settings.json and selected_user.json so your configuration persists across restarts. When running PlexyTrack in Docker, mount a host directory and set PLEXYTRACK_DATA_DIR to that path (for example /data) so the tokens and settings survive container re-creation.

When specifying a custom redirect URI for either service, ensure the same value is configured in your Trakt or Simkl application and passed via the TRAKT_REDIRECT_URI or SIMKL_REDIRECT_URI environment variables. PlexyTrack now honours the X-Forwarded-Proto and X-Forwarded-Host headers, so when running behind a reverse proxy the correct redirect URI is detected automatically. Set a redirect URI explicitly only when you need to override the auto-detected value.

The application uses plexapi version 4.15 or newer (but below 5).

If you don't already have the Trakt or Simkl credentials, please see the next sections on how to obtain them.

Quick Start

1. Install Docker Desktop (Windows/macOS) or docker and docker-compose (Linux).

2. Download or clone this repository and open a terminal inside the folder.

3. Create a file named .env and paste your Plex, Trakt or Simkl details as shown below:

   # Example .env
   PLEX_BASEURL=http://your-plex-ip:32400
   PLEX_TOKEN=your_plex_token
   
   TRAKT_CLIENT_ID=YOUR_TRAKT_CLIENT_ID
   TRAKT_CLIENT_SECRET=YOUR_TRAKT_CLIENT_SECRET
   
   SIMKL_CLIENT_ID=YOUR_SIMKL_CLIENT_ID
   SIMKL_CLIENT_SECRET=YOUR_SIMKL_CLIENT_SECRET
   
   # ...other variables...
   TZ=Europe/Madrid
   

4. Start the application with:

   docker-compose up -d
   

5. Open http://localhost:5030 in your browser and follow the on‑screen steps to authorize Trakt or Simkl and select the Plex user you want to sync.

Once configured, PlexyTrack will keep your libraries in sync on the schedule you choose.

Collections and watchlists

If you mark a list as liked on Trakt, PlexyTrack will create a Plex collection with the same name and add the matching movies or shows found in your library. Likewise, any collection created in Plex will be mirrored as a list on Trakt. Watchlists are also kept in sync both ways, so adding or removing an item in one platform is reflected in the other. When the Simkl provider is selected, your Plex library is copied to the My TV Shows and My Movies sections on Simkl and Plex collections are mirrored as Simkl lists.

Backup and restore

From the web interface you can download a backup file containing your Trakt history, watchlist and ratings. This JSON file can be uploaded again to restore your data at any time. Creating a backup is recommended before starting synchronization for the first time.

Live sync

When Live Sync is enabled on the main page, PlexyTrack will start a webhook endpoint at /webhook. Configure a Plex Webhook to call this URL and the application will trigger an immediate sync whenever an event is received. When the Simkl provider is selected, the received payload is also forwarded to Simkl's own sync/plex/webhook endpoint for instant updates.

Getting a Plex token

1. Open the Plex Web application and sign in.
2. Pick any movie or show and click the three dots in the lower right corner to open Get Info.
3. In the information panel choose View XML. A new tab will display the XML data for that item.
4. Copy the value of X-Plex-Token from the URL bar – that's your token.
5. If you need more details, Plex offers instructions at https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/.

Getting Trakt API credentials

1. Log in to your Trakt account and open https://trakt.tv/oauth/applications.
2. Create a new application. Any name will work and you can use urn:ietf:wg:oauth:2.0:oob as the redirect URL. If you want the authorization code to be filled automatically, set the redirect URL to something like http://localhost:5030/oauth/trakt and configure the same value if you provide a TRAKT_REDIRECT_URI environment variable.
3. After saving the app you will see a Client ID and Client Secret. Keep them handy.
4. Start PlexyTrack and open http://localhost:5030 in your browser. From the Config. tab you can authorize PlexyTrack on Trakt. After authorizing, Trakt will redirect you to the OAuth tab where the code will appear automatically.

Getting Simkl API credentials

1. Sign in to your Simkl account and visit https://simkl.com/apps.
2. Click Create new app, provide any name and set the redirect URL to match http://localhost:5030/oauth/simkl or your SIMKL_REDIRECT_URI.
3. After saving the app you will see a Client ID and Client Secret. Keep them handy.
4. Open PlexyTrack and from the Config. tab choose Configure under Simkl to authorize the app.

Running on Unraid

PlexyTrack is available as a Community Applications template for Unraid.

Installing from Community Applications

1. Open the Apps tab in Unraid and search for PlexyTrack.
2. Click Install to open the template configuration screen.

Template fields

The template exposes the following fields. Fill them in directly from the Unraid UI:

| Field | Container Variable | Where to get it | Required | |---|---|---|---| | Web UI Port | 5030 (TCP) | Default is 5030. Change only if the port conflicts with another container. | Yes | | **Conf