Lyrion MCP Server

A Model Context Protocol (MCP) server for controlling Lyrion Music Server (formerly Logitech Media Server/Squeezebox Server) via its JSON-RPC HTTP interface.

Architecture

This server implements a dual-layer JSON-RPC architecture:

1. MCP Protocol Layer: Communicates over stdin/stdout using JSON-RPC 2.0

   • Stdout is reserved exclusively for MCP responses
   • Logs are sent to stderr for debugging

2. Lyrion Client Layer: Communicates with Lyrion Music Server via HTTP

   • JSON-RPC 2.0 over HTTP to http://LYRION_HOST:LYRION_HTTP_PORT/jsonrpc.js
   • Default: localhost:9000

Features

• JSON-RPC 2.0 over HTTP (MCP protocol compliant)
• Player control (play, pause, stop, power)
• Volume control with mute support
• Track navigation and seeking
• Playlist and library browsing
• Multi-room sync groups
• Sleep timer
• Favorites management
• Display control (brightness, messages)
• Library statistics and scanning
• Player preferences

Installation

Pre-built Binaries

Download pre-built binaries from GitHub Actions:

1. Click the latest workflow run
2. Scroll to Artifacts at the bottom
3. Download the appropriate binary for your platform:

Platform	Artifact
Linux (x86_64)	lyrion-mcp-server-x86_64-unknown-linux-gnu
Windows (x86_64)	lyrion-mcp-server-x86_64-pc-windows-msvc
macOS (Intel)	lyrion-mcp-server-x86_64-apple-darwin
macOS (Apple Silicon)	lyrion-mcp-server-aarch64-apple-darwin

From Source

# Clone the repository
git clone https://github.com/yourusername/lyrion-mcp-server.git
cd lyrion-mcp-server

# Build the release binary
cargo build --release

# The binary will be at target/release/lyrion-mcp-server

Configuration

The server connects to Lyrion Music Server via HTTP JSON-RPC. Configure via environment variables:

# Optional: Override defaults
export LYRION_HOST=localhost     # Default: localhost
export LYRION_HTTP_PORT=9000     # Default: 9000

MCP Configuration

Add to your Claude MCP config (~/.claude/mcp_config.json or desktop app settings):

{
  "mcpServers": {
    "lyrion": {
      "command": "/path/to/lyrion-mcp-server/target/release/lyrion-mcp-server"
    }
  }
}

Available Tools

Server Information (3 tools)

• get_server_version - Get Lyrion version
• get_player_count - Get number of players
• list_players - List all players

Player Control (40+ tools)

• Playback: play, pause, stop, power_on, power_off
• Volume: get_volume, set_volume, volume_up, volume_down, mute_toggle
• Navigation: next_track, prev_track, jump_to_index, seek
• Status: get_player_status, get_current_track
• Playlists: get_playlists, load_playlist, add_playlist, create_playlist, delete_playlist, clear_queue, shuffle_queue, get_playlist_tracks
• Playlist Editing: add_track_to_playlist, add_album_to_playlist
• Queue: add_track_to_queue, add_album_to_queue
• Library: search_tracks, get_genres, get_artists, get_albums, get_album_info, play_song, get_songs_by_artist, get_songs_on_album
• Modes: set_repeat, get_repeat, set_shuffle, get_shuffle

Advanced Features (26 tools)

• Sync Groups: get_sync_groups, get_sync_group, sync_players, unsync_player, unsync_all
• Sleep Timer: get_sleep_timer, set_sleep_timer, cancel_sleep_timer
• Favorites: get_favorites, play_favorite
• Display: show_message, clear_display, set_brightness, get_brightness
• Library Stats: get_library_stats, get_total_songs, get_total_albums, get_total_artists, rescan_library, scan_library, get_scan_progress
• Preferences: get_pref, set_pref

Development

Prerequisites

• Rust 1.82 or later
• A running Lyrion Music Server instance

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy -- -D warnings

# Run all checks
cargo fmt --check && cargo clippy -- -D warnings && cargo test

Testing

Unit Tests

# Run unit tests (no server required - 23 tests for deserializers and types)
cargo test --lib

Integration Tests

Integration tests require a running Lyrion Music Server and are organized into logical suites:

# Run all integration tests (45 tests total)
TEST_PLAYER_ID="aa:bb:cc:dd:ee:ff" cargo test --tests

# Run specific test suite
TEST_PLAYER_ID="aa:bb:cc:dd:ee:ff" cargo test --test playlist_crud
TEST_PLAYER_ID="aa:bb:cc:dd:ee:ff" cargo test --test playlist_editing
TEST_PLAYER_ID="aa:bb:cc:dd:ee:ff" cargo test --test queue_management
TEST_PLAYER_ID="aa:bb:cc:dd:ee:ff" cargo test --test error_handling

# Or with custom settings
LYRION_HOST=192.168.1.22 \
LYRION_HTTP_PORT=9000 \
TEST_PLAYER_ID="Living Room" \
TEST_TRACK_ID="12" \
TEST_ALBUM_ID="1" \
cargo test --tests

Required environment variable:

• TEST_PLAYER_ID - MAC address or name of a test player

Optional environment variables:

• LYRION_HOST - Lyrion server host (default: localhost)
• LYRION_HTTP_PORT - HTTP JSON-RPC port (default: 9000)
• TEST_TRACK_ID - Track ID to test with (default: 12)
• TEST_ALBUM_ID - Album ID to test with (default: 1)
• TEST_PLAYLIST_NAME - Base playlist name for tests (default: auto-generated)
• TEST_TRACK_ID_2 - Second track ID for multi-item tests (default: 13)

Integration test suites:

1. playlist_crud (2 tests)

   • Creating playlists from empty queue
   • Creating and deleting playlists
   • Getting playlist tracks (empty playlists)

2. playlist_editing (3 tests)

   • Adding tracks to playlists
   • Adding albums to playlists
   • Adding both albums and tracks to playlists

3. queue_management (6 tests)

   • Adding tracks to the playback queue
   • Adding albums to the playback queue
   • Adding playlists to the playback queue
   • Clearing the queue
   • Adding multiple items to the queue
   • Loading playlists (replaces current queue)

4. error_handling (11 tests)

   • Non-existent playlists/tracks/players
   • Invalid input values (volume, shuffle mode, repeat mode)
   • Boundary conditions and edge cases

Architecture

src/
├── main.rs       # MCP server entry point
├── lib.rs        # Library exports
├── types.rs      # Common types (JSON-RPC structs)
├── server.rs     # Server loop and request routing
├── tools.rs      # MCP tool definitions
├── handlers.rs   # Tool call handlers
└── lyrion/       # Lyrion JSON-RPC client module
    ├── mod.rs           # Module exports
    ├── client.rs        # HTTP JSON-RPC client
    ├── display.rs       # Display control
    ├── favorites.rs     # Favorites management
    ├── library.rs       # Library statistics and scanning
    ├── modes.rs         # Repeat and shuffle modes
    ├── navigation.rs    # Track navigation
    ├── player_control.rs # Playback and power controls
    ├── playlist.rs      # Playlist and queue methods
    ├── prefs.rs         # Player preferences
    ├── sleep.rs         # Sleep timer
    ├── sync.rs          # Multi-room sync groups
    ├── types.rs         # Response type definitions
    ├── types_tests.rs   # Unit tests for types
    └── volume.rs        # Volume control

tests/
├── common/
│   └── mod.rs           # Shared test utilities and fixtures
├── error_handling.rs    # Error condition and negative path tests
├── playlist_crud.rs     # Playlist CRUD operations tests
├── playlist_editing.rs  # Playlist modification tests
└── queue_management.rs  # Playback queue tests

Protocol

The server communicates with Lyrion Music Server via JSON-RPC over HTTP:

1. Connection: HTTP POST to http://LYRION_HOST:LYRION_HTTP_PORT/jsonrpc.js (default: http://localhost:9000/jsonrpc.js)
2. Request Format:

   {"id": 1, "method": "slim.request", "params": ["player_id", ["command", "param1", "param2"]]}
   

3. Response Format: Same as request with added result field containing the response data
4. Parameters: JSON array, no percent-encoding needed (JSON handles special characters)

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run cargo fmt && cargo clippy && cargo test
5. Submit a pull request

Acknowledgments

• Built for Lyrion Music Server
• Uses the Model Context Protocol
• Based on the Lyrion Music Server JSON-RPC interface