Open source · Local-first · Made for Plex

Rediscover your music.
Build better Plex playlists.

MusicSeed is a local recommendation engine for your Plex collection. It combines sonic similarity, library metadata, popularity, and play history to help you discover tracks that belong together. Start with music you love, review the recommendations, and save the mix to Plex.

Get started How it works

First, configure Plex and import your library. Sonic analysis and popularity enrichment take additional time to prepare. See what setup involves.

LocalRecommendations run on your machine
6 signalsRecommendations with reasons you can inspect
Your musicTracks from your imported Plex collection
Your choicePreview the mix and choose what gets saved

How it works

Prepare your library.
Then explore what fits.

MusicSeed needs your library and its recommendation signals before it can put them to work. Initial preparation takes time, especially for a large collection that Plex has not yet analyzed.

  1. Configure Plex and import your library. Connect your server, choose the music library, and configure access to the Plex databases. MusicSeed imports metadata and play history into its own local store.
  2. Prepare sonic similarity. Let Plex complete sonic analysis, then import those vectors into MusicSeed. Starting Plex analysis and importing its results are separate steps; triggering analysis does not mean the tracks are ready.
  3. Enrich popularity. Configure ListenBrainz, with Spotify as an optional fallback, and run enrichment. Lookups take time and depend on provider availability and track matches. Check coverage before relying on the popularity signal.

Create a playlist from seed tracks

Once your library is prepared, choose one or several tracks you love. Preview related music from your collection, adjust the mix, and save your selection to Plex.

Grow a favorite playlist

Find complementary tracks for a playlist you already enjoy. Review the proposed additions before saving them; tracks already present are skipped when adding.

The recommendation engine

Grounded in the music
you already own.

MusicSeed ranks tracks from your imported Plex library using six signals. Score breakdowns help you understand each recommendation, and library coverage shows which signals have data to work with.

Sonic similarity

Find tracks that sound related, using Plex’s own audio analysis imported into MusicSeed.

Popularity proximity

Find tracks with a similar level of popularity, using optional ListenBrainz enrichment and Spotify fallback.

Style & genre

Use the styles and genres in your library to connect music with shared characteristics.

Era

Bring the release years of your seeds into the mix, with year filters when you want a specific period.

Novelty

Use play history to help surface music you have heard less often.

A mix you can shape

Choose presets, track counts, year ranges, and per-artist limits. Fine-tune individual signal weights in the web UI or CLI; MCP agents can use named presets and filters.

Get started · Prepare your library

Install MusicSeed.
Start preparing your library.

You’ll need Python 3.12+, a Plex Media Server with a music library, and macOS or Linux. Node.js and npm are needed to install the web UI; the app’s runtime is Python only.

From a release archive

Download and unpack a release archive, then run inside its folder:

./scripts/install.sh
musicseed

From source

Clone the repository, install, and start the app:

git clone https://github.com/dafevara/musicseed.git
cd musicseed
./scripts/install.sh
musicseed

Open http://127.0.0.1:8789. The setup wizard helps connect Plex and initialize MusicSeed. Installation is the start: follow the library preparation steps and check import, sonic, and enrichment coverage before building your first mix. The installer includes the web app and CLI.

  1. Connect Plex and import your library. Confirm the server, music library, and database source. For Plex on a NAS or another machine, configure an SSH target in Settings. Imports are incremental and resumable.
  2. Add the signals you want. Import Plex’s sonic vectors after Plex has analyzed your tracks. Optionally enrich popularity with a free ListenBrainz token; Spotify is a credentialed fallback.
  3. Try a recommendation. Choose seed tracks in the web UI or CLI. Inspect the results and signal coverage. You can add an MCP connection later if you want to use an agent.

Choose how you use MusicSeed

One recommendation engine.
Three ways in.

Use the web UI for setup and visual control, the CLI for terminal workflows, or an MCP agent for playlist conversations once your library is prepared. Each uses the same recommendation engine and available data.

Web UI · See and tune the mix

Set up your library, check import coverage, inspect recommendations, adjust signal weights, and save playlists through a local browser interface.

Install the app →

CLI · Work from the terminal

Import, enrich, recommend, and manage playlists with musicseed-cli. Run commands directly for library maintenance and playlist workflows.

Explore the CLI →

MCP · Talk to your agent

After setup and signal preparation, connect a compatible agent through the Model Context Protocol. Search your imported library, preview recommendations, and create or extend Plex playlists through conversation.

Connect your agent →

Optional · Agent integration

Use your prepared library
with an AI agent.

MCP gives a compatible agent access to MusicSeed’s recommendations and playlist tools. Configure Plex, import your library, and prepare sonic and popularity signals through the web UI or CLI first. Connecting an agent uses that work; it does not perform or speed up those preparation steps.

MCP connection instructions

1 · Prepare the MCP environment

This setup uses uv. With uv installed, run from your MusicSeed source folder:

uv sync --locked --project mcp

Keep your shared configuration at ~/.config/musicseed/config.yaml or ~/.musicseed.yaml, so the agent can find it regardless of its working directory.

2 · Register it with your agent

For hosts that accept mcpServers JSON, use this example. Replace the path with your MusicSeed folder; other hosts use their own configuration format.

{
  "mcpServers": {
    "musicseed": {
      "command": "uv",
      "args": [
        "run", "--locked", "--project",
        "/absolute/path/to/musicseed/mcp",
        "musicseed-mcp"
      ]
    }
  }
}

Your agent must be able to find uv; use its absolute executable path if needed. The default stdio connection lets your agent launch MusicSeed on demand, without running the web app. Hosts using a URL can use Streamable HTTP or SSE; see the MCP setup guide.

Documentation

From first connection
to a mix that feels right.

Open the docs →

Built for collectors

Your collection has more
to play.

You have spent years collecting, tagging, and organizing your music. MusicSeed helps you find new paths through it, from a familiar seed track to something you forgot you owned.

The database and recommendation engine run locally. Explore in the web UI, work in the terminal, or connect an agent after preparing your library. MusicSeed fits the way you choose to explore your collection.

MusicSeed is a personal, DIY project by Daniel Valencia, open source under the MIT license. Built for music collectors, self-hosters, and makers who like to understand and shape their tools.

Keep collecting. Keep discovering.

FAQ

Before your first playlist.

What do I need to prepare before using MusicSeed?

Configure your Plex connection and database access, then import library metadata and play history. For sonic similarity, Plex must analyze your tracks and MusicSeed must import the resulting vectors. For popularity, configure an enrichment provider and run its lookups. Check coverage in the web UI. Use the web UI or CLI for this preparation, whether you later use an agent or work directly.

How long does initial preparation take?

There is no fixed setup time. Library size, hardware, how much Plex has already analyzed, and enrichment provider availability all affect it. Sonic analysis and enrichment can take a while; starting a job is not the same as finishing it. Follow progress and coverage in the web UI. MusicSeed imports and enrichment are resumable.

Do all signals need to be ready before I try recommendations?

You can explore recommendations with the data already available. Sonic similarity needs imported Plex analysis vectors, and popularity needs enrichment data. Results reflect that coverage, so a preview from a partially prepared library may differ from one after preparation completes. Connecting an agent does not fill those gaps.

What do I need to get started?

A Plex Media Server with a music library, Python 3.12+, and macOS or Linux. Node.js and npm are needed to install the web UI; its runtime is Python only. The MCP connection example uses uv and a compatible agent. The main installer installs the web app and CLI; MCP is configured separately. Windows is untested.

What makes the recommendations useful?

MusicSeed ranks tracks from your imported collection using sonic similarity, popularity proximity, style, genre, era, and novelty. Recommendation previews include score breakdowns. MCP offers balanced, sonic, discovery, and popular presets, plus filters for year range, track count, per-artist limits, and minimum score. The web UI and CLI also expose individual signal weights.

How does sonic similarity work?

MusicSeed imports Plex's existing sonic analysis vectors into its own local store. For sound-based recommendations, Plex must first analyze your tracks, then you import those vectors through MusicSeed. Other available signals can still contribute when sonic data is missing. MusicSeed does not generate audio embeddings itself.

Does Plex need to run on the same machine?

No. MusicSeed can fetch consistent database snapshots from a remote Plex host over verified SSH. Configure the SSH target in Settings when Plex runs on a NAS or another machine. Saving playlists requires a connection to your Plex server.

Do I need to use an AI agent?

No. The web UI and CLI remain complete ways to use MusicSeed. All three interfaces share the same local recommendation engine. Use the web UI for setup and visual control, the CLI for terminal workflows, or MCP for conversations with an agent.

What can my AI agent do with MusicSeed?

Through MCP, a compatible agent can search your imported library, inspect library coverage and recommendation presets, list Plex playlists, preview recommendations, and create or extend a playlist from a reviewed selection. Library setup, import, and enrichment are handled through the web UI or CLI.

Which agents can connect?

Use an agent that supports MCP servers. The default connection runs MusicSeed as a local subprocess over stdio; Streamable HTTP and SSE are also available for hosts that connect by URL. Connection settings depend on your agent. The MCP setup guide includes a configuration example.

How are playlists reviewed and saved?

Preview recommendations in the web UI, CLI, or through an MCP agent, then review your selection before saving. In MCP, preview tools do not write to Plex; separate write tools receive selected track IDs, and agent instructions call for your approval. Missing or stale IDs reject the write, and retries avoid duplicate additions. MusicSeed reads Plex metadata without editing its database files; playlists are written through the Plex API.

Is MusicSeed free, and where does my data go?

MusicSeed is free and MIT-licensed. Its database and recommendation engine run on your machine. Optional popularity enrichment contacts ListenBrainz or Spotify, and Plex connections may use your network. If you connect a cloud AI agent, track information returned by tools may be sent to that provider. The agent you choose may have its own fees.

Contact

Let's talk.

Bug, idea, or just want to say your library found its match? Reach out.

Source & issues github.com/dafevara/musicseed Report bugs, request features, browse the code Discussions GitHub Discussions Questions and community chat Email dafevara@gmail.com Direct line to the author

Contributing? It's MIT-licensed and pull-requests welcome. For private security reports, see SECURITY.md.