Moonbase, the server plugin for Moonfin!

Moonbase is the server plugin that powers the Moonfin experience on both Jellyfin and Emby.

---

What is Moonbase?

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/.

Installation

Moonbase needs Jellyfin 10.10 or newer or Emby 4.8 or newer. The wiki's Installation page has the steps plus updating and uninstalling.

Jellyfin

The plugin repository is the recommended route, because it updates through the catalog like any other plugin:

1. Open the Jellyfin Dashboard, then go to Administration > Plugins > Repositories.
2. Add a repository:
   • Name: Moonbase
   • URL: https://raw.githubusercontent.com/Moonfin-Client/Plugin/refs/heads/master/manifest.json
3. Go to Catalog, find Moonbase, and install it.
4. Restart Jellyfin.

Advanced: manual install

1. Download the latest Moonfin.Server-x.x.x.x.zip from Releases
2. 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\

3. Restart Jellyfin

Emby

The Emby plugin is a drop-in zip, not a catalog plugin:

1. Download the latest Moonfin.Emby-x.x.x.x.zip from Releases.
2. Extract its contents (Emby.Plugins.Moonfin.dll, SharpCompress.dll, and the web folder) into your Emby plugins folder:

   Platform	Path
   Linux	/var/lib/emby/plugins/
   Docker	/config/plugins/
   Windows	%AppData%\Emby-Server\programdata\plugins\

3. Restart Emby.

Opening the Moonfin Web App

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:

1. Add its plugin repository: https://www.iamparadox.dev/jellyfin/plugins/manifest.json
2. Install File Transformation from the catalog and restart Jellyfin.
3. 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.

Features

• 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.

Configuration

Open your server dashboard, go to Plugins, and select Moonbase. The Admin Guide walks through every tab. 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.

Documentation

The deeper reference material lives in the Wiki:

Contributing

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.

Support and Community

• Issues for bugs and feature requests: GitHub Issues
• Discussions for questions and ideas: GitHub Discussions

Credits

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

License

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