LMS MCP Server

A Model Context Protocol (MCP) server that provides LLM tools with access to the Lyrion Music Server (LMS) via its JSONRPC API.

Table of Contents

• Features
• Installation
• Configuration
• Usage
• API Reference
• Development
• Troubleshooting
• License

Features

This MCP server provides the following tools for interacting with your Lyrion Music Server:

Player Management

• get_players: List all available players
• get_player_status: Get detailed status of a specific player
• test_connection: Test connection to the LMS server

Playback Control

• play_pause: Toggle play/pause for a player
• set_volume: Set player volume (0-100)
• seek: Seek to a specific position in the current track
• play_track: Play a specific track by ID
• set_power: Turn a player on, off, or toggle power
• set_sleep_timer: Set a sleep timer on a player

Mixer / Sound

• set_bass: Set bass level (-100 to 100)
• set_treble: Set treble level (-100 to 100)
• set_balance: Set left/right balance (-100 to 100)
• set_loudness: Enable or disable loudness compensation
• set_mute: Mute or unmute a player

Playlist Management

• playlist_action: Perform playlist actions (play, pause, stop, next, previous, shuffle, repeat)
• get_current_playlist: Get the current playlist for a player
• add_to_playlist: Add a track to the current playlist
• clear_playlist: Clear the current playlist
• jump_to_playlist_index: Jump to a specific track index
• delete_playlist_item: Delete a track from the current playlist
• move_playlist_item: Move a track within the current playlist
• save_playlist: Save the current playlist with a name
• delete_saved_playlist: Delete a saved playlist
• rename_saved_playlist: Rename a saved playlist
• set_shuffle: Set shuffle mode (off, song, album)
• set_repeat: Set repeat mode (off, song, all)

Server & Library

• get_server_status: Get LMS server status and library statistics
• rescan_library: Trigger a library rescan (progressive or full)
• set_random_play: Start or stop a random play mix (tracks, albums, artists, year)

Discovery

• get_years: Get years available in the library
• get_decades: Get decades available in the library
• get_new_music: Get recently added albums
• get_random_albums: Get a random selection of albums

Search and Discovery

• search_tracks: Search for tracks
• search_artists: Search for artists
• search_albums: Search for albums
• get_playlists: Get all available playlists
• get_genres: Get all genres available in the music database
• search_tracks_by_genre: Search for tracks by genre

Online Music Sources

• play_url: Play a direct URL or stream (internet radio, podcast, etc.)
• add_url_to_playlist: Add a direct URL or stream to the current playlist
• get_favorites: Get all favorites (often includes radio stations and online streams)
• add_favorite: Add a URL or stream to favorites
• play_favorite: Play a favorite by item ID
• get_radios: Get radio directory categories and apps (TuneIn, etc.)
• search_radio: Search TuneIn radio stations and podcasts
• play_radio_item: Play a TuneIn radio search result by item ID
• get_apps: Get installed online music apps (TIDAL, Spotify, Qobuz, YouTube, etc.)
• browse_app: Browse an online music app menu
• search_app: Search within an online music app
• play_app_item: Play an item from an online music app by item ID

Installation

1. Clone this repository:

git clone <repository-url>
cd lms-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

1. Copy the example environment file:

cp env.example .env

2. Edit .env with your LMS server settings:

# Lyrion Music Server Configuration
LMS_HOST=localhost
LMS_PORT=9000
LMS_PROTOCOL=http
LMS_TIMEOUT=10000

Configuration Options

• LMS_HOST: IP address or hostname of your LMS server (default: localhost)
• LMS_PORT: Port number of your LMS server (default: 9000)
• LMS_PROTOCOL: Protocol to use (http or https, default: http)
• LMS_TIMEOUT: Request timeout in milliseconds (default: 10000)

Usage

Running the MCP Server

# Development mode
npm run dev

# Production mode
npm start

# Watch mode for development
npm run watch

Using with Claude Desktop

Add the following to your Claude Desktop configuration file:

{
  "mcpServers": {
    "lms": {
      "command": "node",
      "args": ["/path/to/lms-mcp/dist/index.js"],
      "env": {
        "LMS_HOST": "your-lms-server-ip",
        "LMS_PORT": "9000"
      }
    }
  }
}

Using with Other MCP Clients

The server communicates via stdio using the Model Context Protocol. Any MCP-compatible client can connect to it.

API Reference

Player Management Tools

get_players

Returns a list of all available players.

Parameters: None

Returns: Array of player objects with properties like playerid, name, model, ip, etc.

get_player_status

Get detailed status of a specific player.

Parameters:

• playerId (string): The ID of the player to get status for

Returns: Player status object with current track, volume, playback state, etc.

test_connection

Test the connection to the LMS server.

Parameters: None

Returns: Connection status message

Playback Control Tools

play_pause

Toggle play/pause for a player.

Parameters:

• playerId (string): The ID of the player to control

set_volume

Set the volume of a player.

Parameters:

• playerId (string): The ID of the player to control
• volume (number): Volume level (0-100)

seek

Seek to a specific position in the current track.

Parameters:

• playerId (string): The ID of the player to control
• position (number): Position in seconds to seek to

play_track

Play a specific track by ID.

Parameters:

• playerId (string): The ID of the player to control
• trackId (string): The ID of the track to play

Playlist Management Tools

playlist_action

Perform various playlist actions.

Parameters:

• playerId (string): The ID of the player to control
• action (string): Action to perform (play, pause, stop, next, previous, shuffle, repeat)

get_current_playlist

Get the current playlist for a player with complete track information.

Parameters:

• playerId (string): The ID of the player to get playlist for

Returns: Object containing:

• tracks: Array of track objects with complete metadata (artist, title, album, duration, etc.)
• currentTrack: Index of the currently playing track
• totalTracks: Total number of tracks in the playlist
• visibleTracks: Number of tracks visible in the current view

add_to_playlist

Add a track to the current playlist.

Parameters:

• playerId (string): The ID of the player to add track to
• trackId (string): The ID of the track to add

clear_playlist

Clear the current playlist.

Parameters:

• playerId (string): The ID of the player to clear playlist for

Search and Discovery Tools

search_tracks

Search for tracks in your music library.

Parameters:

• query (string): Search query
• limit (number, optional): Maximum number of results (default: 50)

Returns: Array of track objects matching the search query

search_artists

Search for artists in your music library.

Parameters:

• query (string): Search query
• limit (number, optional): Maximum number of results (default: 50)

Returns: Array of artist objects matching the search query

search_albums

Search for albums in your music library.

Parameters:

• query (string): Search query
• limit (number, optional): Maximum number of results (default: 50)

Returns: Array of album objects matching the search query

get_playlists

Get all available playlists.

Parameters: None

Returns: Array of playlist objects

get_genres

Get all genres available in the music database.

Parameters: None

Returns: Array of genre objects with genre name, ID, and favorites URL

search_tracks_by_genre

Search for tracks by genre.

Parameters:

• genre (string): Genre name to search for
• limit (number, optional): Maximum number of results (default: 50)

Returns: Array of track objects with complete metadata (artist, title, album, duration, etc.)

Online Music Source Tools

play_url

Play a direct URL or stream on a player.

Parameters:

• playerId (string): Player ID to control
• url (string): URL or stream to play

add_url_to_playlist

Add a direct URL or stream to the current playlist.

Parameters:

• playerId (string): Player ID to add URL to
• url (string): URL or stream to add

get_favorites

Get all favorites. Favorites often include radio stations, online streams, and playlists.

Parameters:

• limit (number, optional): Maximum number of results (default: 100)

Returns: Array of favorite item objects with id, name, type, url, image, etc.

add_favorite

Add a URL or stream to favorites.

Parameters:

• url (string): URL or stream to add
• title (string): Title for the favorite

play_favorite

Play a favorite by item ID on a player.

Parameters:

• playerId (string): Player ID to play favorite on
• itemId (string): Favorite item ID (the id field from get_favorites)

get_radios

Get radio directory categories and apps (TuneIn, etc.).

Parameters:

• limit (number, optional): Maximum number of results (default: 100)

Returns: Array of radio category/app objects with cmd, name, type, icon, etc.

search_radio

Search TuneIn radio stations and podcasts.

Parameters:

• playerId (string): Player ID to use for searching (TuneIn search requires a real player)
• query (string): Search query
• limit (number, optional): Maximum number of results (default: 50)

Returns: Array of radio search result objects

play_radio_item

Play a TuneIn radio search result by item ID on a player.

Parameters:

• playerId (string): Player ID to play radio on
• itemId (string): Radio item ID (the id field from search_radio)

get_apps

Get installed online music apps such as TIDAL, Spotify (Spotty), Qobuz, YouTube, SoundCloud, Mixcloud, and Podcasts.

Parameters:

• limit (number, optional): Maximum number of results (default: 100)

Returns: Array of app objects with cmd, name, type, icon, etc. Use the cmd value with browse_app and search_app.

browse_app

Browse an online music app menu.

Parameters:

• playerId (string): Player ID to use for browsing
• appCmd (string): App command name (the cmd field from get_apps, e.g. tidal, spotty, qobuz)
• itemId (string, optional): Menu item ID to browse into (omit for top-level menu)
• limit (number, optional): Maximum number of results (default: 50)

Returns: Object with title, count, and items array. Items have id, name, type, image, isaudio, and hasitems.

search_app

Search within an online music app.

Parameters:

• playerId (string): Player ID to use for searching
• appCmd (string): App command name (e.g. tidal, spotty, qobuz)
• query (string): Search query
• searchItemId (string): Search category item ID (e.g. after browsing the TIDAL Search menu, albums might be item 7.3)
• limit (number, optional): Maximum number of results (default: 50)

Returns: Object with title, count, and items array.

play_app_item

Play an item from an online music app by item ID.

Parameters:

• playerId (string): Player ID to play on
• appCmd (string): App command name (e.g. tidal, spotty, qobuz)
• itemId (string): Item ID to play (the id field from browse_app or search_app)

Player Control Tools

set_power

Turn a player on, off, or toggle power.

Parameters:

• playerId (string): Player ID to control
• state (string): on, off, or toggle

set_sleep_timer

Set a sleep timer on a player in seconds.

Parameters:

• playerId (string): Player ID to control
• seconds (number): Sleep timer in seconds (0 to cancel)

Mixer / Sound Tools

set_bass

Set bass level on a player.

Parameters:

• playerId (string): Player ID to control
• level (number): Bass level from -100 to 100

set_treble

Set treble level on a player.

Parameters:

• playerId (string): Player ID to control
• level (number): Treble level from -100 to 100

set_balance

Set left/right balance on a player.

Parameters:

• playerId (string): Player ID to control
• level (number): Balance from -100 (left) to 100 (right)

set_loudness

Enable or disable loudness compensation.

Parameters:

• playerId (string): Player ID to control
• enabled (boolean): true to enable, false to disable

set_mute

Mute or unmute a player.

Parameters:

• playerId (string): Player ID to control
• muted (boolean): true to mute, false to unmute

Playlist Editing Tools

jump_to_playlist_index

Jump to a specific track index in the current playlist.

Parameters:

• playerId (string): Player ID to control
• index (number): Track index to jump to (0-based)

delete_playlist_item

Delete a track from the current playlist by index.

Parameters:

• playerId (string): Player ID to control
• index (number): Track index to delete (0-based)

move_playlist_item

Move a track within the current playlist.

Parameters:

• playerId (string): Player ID to control
• fromIndex (number): Source track index
• toIndex (number): Destination track index

save_playlist

Save the current player playlist as a named playlist.

Parameters:

• playerId (string): Player ID whose current playlist to save
• name (string): Name for the saved playlist

delete_saved_playlist

Delete a saved playlist.

Parameters:

• playlistId (string): Saved playlist ID (the id field from get_playlists)

rename_saved_playlist

Rename a saved playlist.

Parameters:

• playlistId (string): Saved playlist ID
• name (string): New name for the playlist

Playback Mode Tools

set_shuffle

Set shuffle mode on a player.

Parameters:

• playerId (string): Player ID to control
• mode (string): off, song, or album

set_repeat

Set repeat mode on a player.

Parameters:

• playerId (string): Player ID to control
• mode (string): off, song, or all

set_random_play

Start or stop a random play mix.

Parameters:

• mode (string): tracks, albums, artists, or year
• enabled (boolean): true to start, false to stop

Server & Library Tools

get_server_status

Get LMS server status and library statistics (version, total albums/artists/songs, last scan, etc.).

Parameters: None

Returns: Server status object

rescan_library

Trigger a library rescan.

Parameters:

• mode (string, optional): progressive (scan for changes) or full (wipe cache and rescan), default progressive

Discovery Tools

get_years

Get years available in the music library.

Parameters:

• limit (number, optional): Maximum number of results (default: 100)

Returns: Array of year objects

get_decades

Get decades available in the music library.

Parameters:

• limit (number, optional): Maximum number of results (default: 100)

Returns: Array of decade objects

get_new_music

Get recently added albums.

Parameters:

• limit (number, optional): Maximum number of results (default: 50)

Returns: Array of album objects

get_random_albums

Get a random selection of albums.

Parameters:

• limit (number, optional): Maximum number of results (default: 50)

Returns: Array of album objects

Development

Project Structure

src/
├── index.ts          # Main entry point
├── mcp-server.ts     # MCP server implementation
├── lms-client.ts     # LMS JSONRPC client
├── types.ts          # TypeScript type definitions
└── config.ts         # Configuration management

Building

npm run build

Development Mode

npm run dev

Watch Mode

npm run watch

Troubleshooting

Connection Issues

1. Verify your LMS server is running and accessible
2. Check the LMS_HOST and LMS_PORT configuration
3. Test the connection using the test_connection tool
4. Ensure your LMS server allows JSONRPC requests

Common Issues

• "LMS request failed": Check network connectivity and LMS server status
• "Invalid player ID": Use get_players to see available player IDs
• "Unknown tool": Ensure you're using the correct tool names from the API reference

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.