# lyrion-mcp

MCP server for [Lyrion Music Server](https://lyrion.org/) / Logitech Media Server.

It lets an AI agent inspect and control LMS players through the LMS JSON-RPC API:
players, playback, volume, playlists, favorites, radio, library search and library browsing.

## Features

### Server and players

- Test LMS connectivity
- Read server status, version, library statistics and scan progress
- List players
- Resolve players by LMS id, exact name, or unique name fragment
- Read detailed player status and current playlist

### Playback controls

- Play, pause, toggle play/pause, stop
- Previous / next
- Set volume
- Power on/off/toggle
- Seek to position
- Sleep timer
- Shuffle and repeat modes
- Sync / unsync players

### Playlist and playback sources

- Show current playlist
- Clear current playlist
- Load/play or append a library track by track id
- Play a direct URL/stream
- List saved LMS playlists
- Play a saved playlist by playlist id
- List favorites
- List top-level radio providers/categories

### Library browse/search

- Search tracks, albums and artists
- List genres, albums, years
- Browse music folders
- List an album's tracks
- List an artist's albums or tracks
- Trigger LMS library rescan

### Diagnostics

- Read-only raw JSON-RPC helper for safe troubleshooting commands.

## Tools

- `lms_test_connection`
- `lms_server_status`
- `lms_players`
- `lms_player_status`
- `lms_play`, `lms_pause`, `lms_play_pause`, `lms_stop`
- `lms_next`, `lms_previous`
- `lms_set_volume`, `lms_set_power`
- `lms_seek`, `lms_sleep`
- `lms_set_shuffle`, `lms_set_repeat`
- `lms_sync`, `lms_unsync`
- `lms_playlist`, `lms_clear_playlist`
- `lms_play_track`, `lms_add_track`, `lms_play_url`
- `lms_saved_playlists`, `lms_play_playlist`
- `lms_favorites`, `lms_radios`
- `lms_search_tracks`, `lms_search_albums`, `lms_search_artists`
- `lms_genres`, `lms_albums`, `lms_years`
- `lms_music_folder`, `lms_album_tracks`, `lms_artist_albums`, `lms_artist_tracks`
- `lms_rescan_library`
- `lms_raw_readonly`

## Configuration

Environment variables:

| Variable | Default | Description |
|---|---:|---|
| `LMS_HOST` | `host.docker.internal` | LMS hostname/IP |
| `LMS_PORT` | `9000` | LMS HTTP port |
| `LMS_PROTOCOL` | `http` | LMS protocol |
| `LMS_URL` | derived | Full JSON-RPC endpoint override |
| `LMS_TIMEOUT` | `10` | JSON-RPC timeout in seconds |
| `MCP_HOST` | `0.0.0.0` | MCP bind host |
| `MCP_PORT` | `8310` | MCP SSE port |

## Docker

```bash
docker build -t lyrion-mcp .
docker run --rm -p 8310:8310 \
  -e LMS_URL=http://host.docker.internal:9000/jsonrpc.js \
  lyrion-mcp
```

MCP endpoint:

```text
http://localhost:8310/sse
```

## Docker Compose

```yaml
services:
  lyrion-mcp:
    image: ghcr.io/simoneb79/lyrion-mcp:latest
    environment:
      LMS_URL: http://host.docker.internal:9000/jsonrpc.js
    ports:
      - "8310:8310"
    restart: unless-stopped
```

## Example client config

```json
{
  "mcpServers": {
    "lyrion-mcp": {
      "url": "http://localhost:8310/sse"
    }
  }
}
```

## Notes

- This server does not require LMS credentials by default because standard LMS JSON-RPC deployments are usually LAN-local. Put it behind your normal network controls.
- Exposing playback controls to an AI agent can change what is playing on your speakers. Review agent permissions accordingly.

## License

MIT