Moonbase is a server plugin for Jellyfin and Emby that gives every Moonfin client its shared backbone. It syncs your settings across devices, hosts the Moonfin web app right on your server, adds extra rating sources, connects your library to Seerr, and gives admins server-wide defaults and tools.
Recommended: if you use any Moonfin client, install Moonbase on your server for the best experience.
This repo ships two plugins from one place: a Jellyfin plugin under Jellyfin/ and an Emby plugin under Emby/.
The plugin repository is the recommended route, because it updates through the catalog like any other plugin:
- Open the Jellyfin Dashboard, then go to Administration > Plugins > Repositories.
- Add a repository:
- Name:
Moonbase - URL:
https://raw.githubusercontent.com/Moonfin-Client/Plugin/refs/heads/master/manifest.json
- Name:
- Go to Catalog, find Moonbase, and install it.
- Restart Jellyfin.
Advanced: manual install
- Download the latest
Moonfin.Server-x.x.x.x.zipfrom Releases - Extract it into your Jellyfin plugins folder:
Platform Path Linux /var/lib/jellyfin/plugins/Moonfin/Docker /config/plugins/Moonfin/Windows %ProgramData%\Jellyfin\Server\plugins\Moonfin\ - Restart Jellyfin
The Emby plugin is a drop-in zip, not a catalog plugin:
- Download the latest
Moonfin.Emby-x.x.x.x.zipfrom Releases. - Extract its contents (
Emby.Plugins.Moonfin.dll,SharpCompress.dll, and thewebfolder) into your Emby plugins folder:Platform Path Linux /var/lib/emby/plugins/Docker /config/plugins/Windows %AppData%\Emby-Server\programdata\plugins\ - Restart Emby.
Moonbase serves the Moonfin web app on your own server, so you can open and bookmark it directly:
https://your-server-host/Moonfin/Web/
Not loading after a fresh install? Run the Moonfin Startup task once (Dashboard > Scheduled Tasks), then refresh your browser.
Advanced: a Moonfin button in the stock Jellyfin web header
On Jellyfin, you can add a one-click Moonfin button to the stock web header (next to SyncPlay) by installing the File Transformation plugin:
- Add its plugin repository:
https://www.iamparadox.dev/jellyfin/plugins/manifest.json - Install File Transformation from the catalog and restart Jellyfin.
- Force refresh your browser.
To hide the button while keeping the plugin, add this to Branding > Custom CSS:
.headerMoonfinButton { display: none !important; }On Emby, the web app is served the same way at /Moonfin/Web/, but there's no header button because Emby has no equivalent injection path.
- Cross-device settings sync, so your preferences follow you between web, TV, mobile, and desktop, with an optional per-device profile for desktop, mobile, and TV.
- The Moonfin web app hosted at
/Moonfin/Web/, running side by side with the stock web interface. - Media bar and home screen data resolved on the server and shared across clients.
- Extra rating sources through MDBList and TMDB, with the API keys kept on the server.
- Seerr integration with a built-in proxy, single sign-on, and optional request and issue notifications. The step-by-step guide is Seerr Setup.
- Push notifications that reach Moonfin apps even when they are closed, covering Seerr activity, new media added to your library, and admin broadcasts. See Seerr Notifications.
- Admin tools for setting server-wide defaults across every client setting, pushing them to existing users, and broadcasting a message to everyone at once.
- Server messages: an admin can write a note (title, Markdown body, colour, audience, start and end dates, an optional link button) that shows up in people's apps, even if they were offline when it was sent.
- Custom themes with a built-in editor, plus server-side upload and validation.
- Retro games support for browsing and playing game libraries, with saves synced per user. See Retro Games.
- Custom rows built from MDBList and IMDb lists, cached on the server.
- An active downloads dashboard with live transcode metrics in the admin panel, plus a per-client view so a transcoded download can show its own progress and ETA.
- Personal ratings served back to clients, so a library can be sorted by your own rating and filtered by liked or disliked, which neither server can do on its own.
- Audiobook bookmarks and notes stored on the server and synced between clients.
Open your server dashboard, go to Plugins, and select Moonbase. The main things to set up:
- Your Seerr URL and whether Seerr is enabled
- Shared MDBList and TMDB API keys, so individual users don't need their own
- Whether Moonbase Sync is on (required for the Seerr and ratings integrations)
- Default user settings that new users inherit, with a button to push them to existing users
- Server messages and the quick broadcast
- Web startup options and custom theme uploads
Users change their own preferences from the in-app settings page in any Moonfin client. Settings are stored per user and shared across clients, with an optional per-device override for desktop, mobile, and TV.
Advanced: the Defaults tab
The Defaults tab covers every client setting in its own subtab, from General Style and Details Screen through Playback and Integrations. Each control mirrors what the clients actually offer, so a default set here is one a client can honor. A setting left on Not set (user decides) passes the user's own choice through.
The deeper reference material lives in the Wiki:
| Page | What it covers |
|---|---|
| API Reference | Every plugin endpoint, with methods, auth, the Seerr config response, and the server messages endpoints |
| Settings Sync | How sync works, the settings envelope, and the full list of synced settings |
| Data Locations | Where the plugin stores user settings, themes, saves, and caches on the server |
| Retro Games | Game libraries, cores, ROMs, BIOS, saves, and in-browser play |
| Seerr Setup | The plain step-by-step guide to connecting Seerr |
| Seerr Notifications | Push delivery, webhooks, notification types, and self-hosted relays |
| Themes | The theme editor and custom theme uploads |
| Reverse Proxy and Seerr | Path forwarding and Seerr single sign-on behind a proxy |
| Building from Source | Building the Jellyfin and Emby plugins from this repo |
Contributions are welcome. Check the existing issues first, open an issue before starting a large change, match the existing code style, and test your changes on desktop and mobile. Features that would help all Jellyfin or Emby users are worth proposing upstream first.
To submit a change, fork the repo, create a feature branch, make your changes with clear commit messages, and open a pull request with a clear description.
- Issues for bugs and feature requests: GitHub Issues
- Discussions for questions and ideas: GitHub Discussions
Moonfin is built on the work of others:
- Jellyfin Project for the foundation and upstream codebase
- Druidblack for the original MDBList Ratings plugin
- Moonfin Contributors for everything they have added to the project
This project is licensed under GPL-3.0. See the LICENSE file for details.
Moonfin is an independent project and is not affiliated with the Jellyfin or Emby projects.
Back to the main Moonfin project