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

1. Install dependencies:

npm install

1. Build the project:

npm run build

Configuration

1. Copy the example environment file:

cp env.example .env

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