Sola MPD

Sola MPD is an MPD client focused on usability with flexible browsing and search. It runs as a web application (Docker) or a desktop application (Experimental: supporting Windows, macOS and Linux).

The primary goal of this client is to help users efficiently find specific songs within large music libraries and freely organize them into a queue and playlists. If you're looking for a table-oriented UI for better music management, this client might be a good fit. However, if you're seeking a player with fancy visual design, this may not be what you're looking for.

This client has the following features:

• Playback control (Play, Resume, Next, and so on)
• Play queue
• Flexible metadata browser (inspired by GMPC)
• MPD Playlist management
• Flexible search
  • =, !=, has, regular expression, etc
  • Flexible AND/OR combinations
  • Saved searches (a.k.a Smart Playlist inspired by MusicBee)
• Database file tree
• Quick filtering box (inspired by MusicBee)
• Plugin for integration with other services
• Intuitive song table editing (powered by AG Grid)
• Multiple MPD servers
• Dark theme
• All songs (Simple full-text search)
• Responsive layout for tablets
• Supports touch devices
• Browse recently added artists, albums and composers
• Playlist sync with Subsonic API compatible service (via plugin)
• Advanced search (Beta, requires lainbow integration)
  • Text-to-Music search (MuQ-MuLan)
  • Similarity search (MuQ)
• MCP server (Beta) for LLM-driven library analysis and control
  • Playback / queue / playlist control tools
  • Structured analytics (top artists, decade breakdown, recently-added per artist, etc.)
  • Read-only SQL queries against an in-memory mirror of the library

On the other hand, the following features are out of scope for now:

• Cover art

Feel free to file an issue if you are interested in any of missing capabilities.

Sola MPD only supports MPD version 0.21 or later.

Some features may use MPD's API in a suboptimal way (e.g., loading all songs at once). While the client has been tested and works well in my environment (with a library of approximately 85,000 songs), it might consume excessive memory with significantly larger libraries.

Pre-built desktop applications for Windows, macOS, and Linux are available on the Releases page. The desktop application is currently experimental and may have limitations compared to the web application.

1. Download the appropriate installer for your platform from the latest release
2. Install and launch the application
3. In the setup dialog, enter the endpoint of your MPD server

The web application needs to be deployed on your server in the local network.

It can be the same server as the MPD server or on a different server, as long as it can communicate with the MPD server.

Sola MPD only requires Docker and Docker Compose to be installed on the server.

If you are using the latest version of Docker, the compose command is already included. Otherwise, you need to install it separately.

1. Ensure a docker process is running on the server

   docker ps

   If you have any issues, please confirm if you installed Docker correctly.

2. Clone this repository on your server and check out the latest release tag

   git clone https://github.com/prokosna/sola_mpd.git
   cd sola_mpd
   git checkout $(git tag --sort=-v:refname | head -n 1)

   The main branch may contain unreleased changes; running from a release tag is recommended.

3. [Optional] Edit the docker-compose.yaml file if you want to change the port or other configurations

   $ vi docker-compose.yaml
   

4. For users migrating from docker/start.sh: If you were using the previous version with docker/start.sh, run the migration script before starting the new version:

   ./docker/migrate_db.sh

   This will copy your existing database from the old sola_db volume to the new one.

5. Start the application

   docker compose up -d

6. Access to http://[Your Server IP]:3000 (or the port you configured) from your browser

7. In the setup dialog, please enter the endpoint of your mpd server which can be accessed from the Sola MPD server.

   If you are using bridge mode and MPD is running on the same server, you need to use "host.docker.internal" instead of "localhost".

Stop the running container, fetch the latest release tag and rebuild the container.

$ cd sola_mpd
$ docker compose down
$ git fetch --tags
$ git checkout $(git tag --sort=-v:refname | head -n 1)
$ docker compose up --build -d

Released tags are listed on the Releases page. The main branch may contain unreleased changes; running from a release tag is recommended.

You can unlock the following features by setting up lainbow.

• Text-to-Music search (MuQ-MuLan)
• Similarity search (MuQ)

Once you have set up lainbow, you can just uncomment the following line in docker-compose.yaml,

      args:
        LAINBOW_ENDPOINT: "http://your.lainbow.endpoint:port/"

then restart the container.

$ docker compose down
$ docker compose up --build -d

Sola MPD requires MuQ and MuQ-MuLan embeddings in the vector database for these features. After restarting the container, the "Advanced Search" tab will be available in the Settings page. If you use Settings > Advanced Search > Scan Library and Analyze buttons to prepare the vector database, only MuQ and MuQ-MuLan embeddings will be generated.

Please note that lainbow requires a NVIDIA GPU to generate embeddings. It works with CPU but it takes much longer time to generate embeddings.

This feature may require some engineering skill to set up. Feel free to let me know if you are interested in this feature but having some trouble setting it up.

Sola MPD exposes a Model Context Protocol server so LLM clients (Claude Code, Claude Desktop, etc.) can browse and analyze your library, drive playback, and run read-only SQL queries against an in-memory mirror of all songs. The intent is not to wrap MPD commands one-for-one but to support multi-angle questions such as "which artists have I not added music from in two years?" or "break down my library by decade and format."

The server runs on the same Express process as the web UI, listening at POST /mcp over the Streamable HTTP transport in stateless mode. It uses the MPD profile currently selected in the Sola MPD UI.

Both protocol eras are served from that one endpoint: the 2026-07-28 revision and, for clients that have not adopted it yet, the earlier 2025-11-25 through 2024-10-07 revisions. The era is negotiated per request, so no client-side configuration is needed either way.

Point any MCP client at http://[Your Server IP]:[Sola MPD port]/mcp (the same port as the web UI — 3000 by default, see docker-compose.yaml if you changed it).

library_query_sql accepts a single SELECT / WITH / EXPLAIN statement and runs it against an in-memory SQLite mirror of MPD.listallinfo. The schema is embedded in the tool description so the LLM can construct queries directly. The mirror is rebuilt only when MPD's database changes, so analytical queries are fast even on large libraries.

Sola MPD has a plugin system to integrate with other services.

For example, I have a use case to synchronize MPD songs with a playlist in an application compatible with Subsonic API and have developed the Subsonic plugin.

To use the Subsonic plugin:

1. Uncomment the Subsonic plugin in docker-compose.yaml

2. Run the plugin container with Sola MPD

   $ docker compose up --build -d
   

3. On the Plugin page in Sola MPD, enter the plugin endpoint (in this case [Your Server IP]:3001) and configure the plugin following a dialog.

4. When the plugin is available, you will see Sync with Subsonic in the right-click context menu and you can create a playlist with selected songs on Sola MPD as long as the exact same songs are available on Subsonic as well.

This plugin is quite specific to my use case, but you can use this as a reference to develop a custom plugin for your use case.

Sola MPD is written in TypeScript with React, Vite, Protocol Buffers, Jotai, etc.

# 1. Install dependencies, set up a husky hook for format/lint
$ pnpm install

# 2. Build the shared package first
$ pnpm --filter @sola_mpd/shared build

# 3. Run dev servers
$ pnpm dev