MyLists

The all-in-one media tracking platform.

MyLists is a comprehensive, web-app designed to help you organize and track your movies, TV series, anime, manga, books, and video games in one unified interface.

Key Features

• Multi-Media lists: Dedicated lists for Movies, Series, Anime, Manga, Books, and Games.
• Dynamic Lists: Save rules across your media lists and see live matches, created manually or through a connected assistant.
• Upcoming Media: Get notified when new Media are released.
• Advanced Analytics: Visualize your habits with detailed stats, trends, and platform-wide insights.
• Daily Moviedle: A daily guessing game to test your movie knowledge.
• Achievements System: Earn unique badges and track your progress as you consume more media.
• Secure Authentication: Robust user management powered by Better-Auth.

Quick Start

Ensure you have Bun installed on your machine.

MCP insight queries also require the system SQLite shared library (libsqlite3-0 on Debian/Ubuntu, sqlite on Arch Linux). Docker includes it. The isolated query process uses this library with memory accounting enabled to enforce its 128 MiB SQLite heap limit; Bun's bundled SQLite disables that accounting starting in Bun 1.4.4.

1. Clone the repo

   git clone https://github.com/crossoufire/MyLists.git
   cd MyLists
   

2. Install deps

   bun install --frozen-lockfile
   

3. Configure the env file

   Create a .env file in the root directory and set the three required security values:

   cp .env.example .env
   openssl rand -hex 32
   

   Run the OpenSSL command twice and use the generated values for ADMIN_TOKEN_SECRET and BETTER_AUTH_SECRET, then choose an ADMIN_PASSWORD of at least 8 chars. All other values have defaults or enable optional features.

4. Initialize Database Initialize a new SQLite database in the instance directory.

   bun run new:db
   

5. Create a new user To create a new user without email verification, OAuth2 setup, and with different roles (user, manager, admin), you can use the CLI:

   bun run cli -- create-user \
     --email [email protected] \
     --password "change-me-strong-password" \
     --username admin \
     --role admin
   

6. Run the Dev Server

   bun run dev
   

Commit bun.lock alongside package.json when updating dependencies. Deployment uses the committed lockfile without resolving new versions.

Imports with cron

Imports are processed using the import-drain CLI. Schedule it regularly (i.e., every 2 min). Linux flock from util-linux prevents overlapping drain workers.

---

Environment Variables

Below is an explanation for each key found in .env.example:

Variable	Description	Required	Default
Main Configuration
DATABASE_URL	SQLite database path	❌	./instance/site.db
VITE_BASE_URL	Base URL used by the frontend	❌	http://localhost:3000
VITE_CONTACT_MAIL	Email used to be contacted by users	❌
File Management
UPLOADS_DIR_NAME	Folder name where uploaded files are stored	❌	static
BASE_UPLOADS_LOCATION	Path to the uploads dir (relative or absolute)	❌	./public/static/
Admin Access
ADMIN_PASSWORD	Admin dashboard privilege-escalation password	✅
ADMIN_TOKEN_SECRET	Secret key for admin access token signing	✅
ADMIN_TTL_COOKIE_MIN	Lifespan of the admin session cookie (in minutes)	❌	10
Admin Mail Service
ADMIN_MAIL_USERNAME	Gmail address used to send application emails	❌
ADMIN_MAIL_PASSWORD	Gmail password or app password	❌
Cache / Redis
CACHE_TTL_MIN	Cache duration (in minutes)	❌	5
REDIS_ENABLED	Enables Redis-backed cache, rate limits, and API monitoring	❌	false
REDIS_URL	Redis connection string, required only if Redis is enabled	❌	redis://localhost:6379
Authentication
BETTER_AUTH_SECRET	Secret used by Better Auth for encryption	✅
OAuth2 Providers
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	GitHub OAuth2 credentials	❌
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google OAuth2 credentials	❌
API Keys
THEMOVIEDB_API_KEY	Enables movie, series, and anime external data through TMDB	❌
GOOGLE_BOOKS_API_KEY	Enables external book search/details through Google Books	❌
MAL_CLIENT_ID	Enables manga data and anime genres through MyAnimeList	❌
IGDB_CLIENT_ID / IGDB_CLIENT_SECRET	Enables game external data through IGDB	❌
LLM Integration (Optional)
LLM_MODEL_ID	Model ID (OpenRouter) used to generate book genres	❌	google/gemini-2.5-flash-lite
LLM_BASE_URL	Base URL for the chosen LLM API	❌	https://openrouter.ai/api/v1
LLM_API_KEY	API key token for the LLM provider	❌

---

Redis Setup

Redis caching is optional.

• To run without Redis, set:

  REDIS_ENABLED=false
  

• To use Redis, ensure Redis is available and configured:

  REDIS_ENABLED=true
  REDIS_URL=redis://redis:6379
  

• Redis is used for shared caching, rate limits, provider cooldowns, and API monitoring rollups.

• The web app, import worker, and scheduled tasks must use the same Redis instance.

• Keep Redis data persistent to retain pending monitoring rollups across restarts.

• Without Redis, these controls use memory in each process and reset when that process exits.

• Import progress and retry times are stored in SQLite in both modes and survive worker restarts.

• The admin API monitoring page will not collect outbound API rollups without Redis.

---

Optional Feature Availability

Missing optional config does not prevent MyLists from starting. Login and registration only show configured auth methods.

• Without admin mail credentials, email registration, password reset, email changes, and mail-dependent maintenance are disabled. Email login still works for verified accounts created with the create-user CLI.
• GitHub and Google OAuth are enabled when their complete client ID/secret pair is present.
• Without TMDB, movie, series, and anime external search/details are unavailable. Without IGDB, game external search/details are unavailable.
• Without MAL_CLIENT_ID, manga external search/details are unavailable and anime uses TMDB genres without MyAnimeList enrichment. Register an API client at MyAnimeList API Configuration.
• Without GOOGLE_BOOKS_API_KEY, external book search/details are unavailable. Existing local books remain usable. Requests are limited to one per second, with no local daily quota. With Redis enabled, daily request counts are available in Admin > API Monitoring > Daily Provider Calls (UTC days), including retries. Quota errors returned by Google still pause requests.
• Without LLM_API_KEY, book genre enrichment is skipped with a task warning.

For every optional credential pair, either set both values or leave both blank. A partial pair is treated as a config error.

---

LLM Integration (Optional)

The LLM is exclusively used to generate genre data for books since Google Books does not provide genre metadata. You can choose how this background task runs:

1. Manually, by executing it with the CLI
2. Automatically, using a scheduled cron job

When LLM_API_KEY is absent, direct and scheduled enrichment runs are skipped with a log.

---

Assistant connections (MCP)

MyLists supports assistants that use OAuth + MCP Streamable HTTP. To connect one, open Settings → Connected Apps, copy the /api/mcp URL, and add it as a remote MCP server. Users can grant read-only or write access and disconnect it at any time.

Setup

Set VITE_BASE_URL to your public HTTPS origin in production. For an existing database:

bun run dk migrate

New databases created with bun run new:db already include the OAuth tables. No separate MCP server or shared API key is required.

Local ChatGPT testing

Expose port 3000 through an HTTPS tunnel and set:

VITE_BASE_URL=https://your-tunnel.example

Restart bun run dev, sign in through the tunnel's /login page, then add:

https://your-tunnel.example/api/mcp

to ChatGPT as an OAuth MCP server.

Tools

The integration supports all the mylists media types. Assistants cannot change account settings, delete entries, access collections, or inherit admin privileges.

Media tools call existing website server functions and return their results:

• search_catalog — search external catalogs using the website's provider and advanced filters
• game_search_options — get game genre/platform options for catalog searches
• search_my_list — browse the connected user's list with the website's list arguments
• my_list_filters, search_my_list_filters — read or search list filter values
• media_details — read catalog details and the user's tracking state
• tv_seasons, game_platforms — read seasons or compatible game platforms
• media_history, my_tags — read tracking history or existing tags
• resolve_catalog_media — obtain a MyLists mediaId from a provider apiId
• add_media — add a MyLists media item with an optional status
• update_media — apply one tracking update using the website's payload
• edit_media_tag — attach or detach a tag on one entry
• query_mylists — inspect the analysis schema or run read-only SQL on the connected user's data
• dynamic_list_schema — get the validated JSON rules and starter specifications for dynamic lists
• preview_dynamic_list — check the current matches for a specification without saving it
• list_dynamic_lists — read saved specifications and their page URLs
• create_dynamic_list — save a specification and return its page URL (requires write access)

Dynamic-list metadata rules are grouped by media type in filters.mediaFilters. For example, movies.actors filters movies without excluding books in the same list. dynamic_list_schema returns the supported filter keys for each type, matching the website's tracking-list filters.

User identity is supplied by the connection. Adding, rating, and editing tags are separate operations, just like on the website. update_media returns kind: "saved" after saving, or kind: "correction-required" with an activity preview before a correction can be confirmed.

For SQL analysis, call query_mylists with action: "schema" first, then use action: "sql" with one SQLite SELECT statement (CTEs are supported). Bind $name placeholders with parameters: { name: value }. Queries run in a separate process against an in-memory snapshot of the user's active lists, visible monthly activity, attached tags, seasons, and related catalog metadata. Account credentials, other users' data, and collections are excluded.

Results include columns, rows as arrays in column order, snapshot timestamps, and timings. maxRows defaults to 200 and cannot exceed 1,000; check truncated before treating results as complete. Query execution is limited to five seconds and SQL results to 256 KiB.

OAuth

Scopes:

mylists:read
mylists:write
offline_access

Access tokens expire after 15 minutes. Disconnecting an assistant invalidates its tokens and refresh tokens.

OAuth discovery:

/.well-known/oauth-protected-resource
/.well-known/oauth-authorization-server/api/auth

After updating the server, refresh the assistant's tool list so it discovers any MCP tool changes.

Contributing

Run the same checks as CI after new deps install:

bun install --frozen-lockfile
bun run routes:generate
bun run lint
bun run typecheck
bun run test

Route gen is required on fresh checkout because routeTree.gen.ts is not committed. CI uses Bun 1.4.2. Three Redis integration tests require MYLISTS_TEST_REDIS_URL pointing to a Redis instance. They pause that server and must not use a dev or prod Redis. CI has an isolated Redis service.

For browser tests, install Chromium once, then run the suite:

node node_modules/@playwright/test/cli.js install chromium
bun run test:e2e

Playwright runs on Node (CI uses Node 24), the app, database fixtures, and import worker run on Bun. The runner creates and removes a temp workspace. Two parallel workers each have their own SQLite db, uploads and dev server (ports 4173 and 4174). Each worker applies the migrations and resets its fixtures before every test. Separate Vite caches in node_modules/.vite-e2e/ are retained between runs. Use --workers=1 for a sequential run. Email, social OAuth, external media providers, and Redis are disabled for browser tests. Use bun run test:e2e --headed to watch, or bun run test:e2e --grep 'signs in' to run one journey. Failed runs keep traces and screenshots in test-results/, with an HTML report in playwright-report/.

Browser tests live with the routes as -*.e2e.ts. The prefix keeps them out of the generated route tree. Vitest only discovers src/**/*.test.{ts,tsx}.

Feature tests use signIn(page, account) from scripts/e2e/fixtures.ts to authenticate through the API, then navigate directly to the page under test. Keep form-based sign-in checks in the login journey to avoid repeating that setup in every browser test.

Contributions are welcome!
If you’d like to improve MyLists, fork the repo, create a feature branch, and open a pull request.

---

Built with ❤️ using Bun, Drizzle, Better-Auth, React, TypeScript, and TanStack.