lms-mcp-server

MCP server for Lyrion Music Server (LMS). Lets Claude query the music library ("what John Coltrane albums do I have?", "which albums did I add this month?") and control players ("play the latest Mali Sheard album in the office").

Runs as a streamable HTTP MCP server. Also records play history by polling player status, since LMS does not store last-played dates - "what have I played this week?" works from the day the server starts. Play counts are whole-album listening sessions (not tracks heard), and each play records the release year and the date the album was added to the library, so "this year's releases, ordered by how much I've played them" is answerable from history alone.

This is an opinionated server, and the opinion is that music comes in albums:

• The album is the default unit. "Play Vamala by Champs" plays the whole album. Single tracks are for when you ask for one explicitly ("play the song Vamala") - the tool descriptions steer the model the same way.
• Artists mean album artists. "Albums by John Coltrane" returns the albums he made, not every tribute album he has a guest solo on. Artist queries use LMS's ALBUMARTIST role, matching the "Album Artists" browse view.
• Local files beat streaming copies. If an album (or track) exists both as local files and as a synced online-library copy (e.g. Qobuz favourites), only the local version is surfaced. Online-only albums still appear.

Code and docs are 100% Claude

Tools

Tool
list_players	Players/rooms with power and playing state
search_albums	Albums by free text and/or album artist; sort by newest or random
search_tracks	Individual tracks, for explicit single-song requests
get_recently_added_albums	Albums added in the last N days, with added dates
get_recently_played_albums	Albums played in the last N days, from the server's own history
play_album	Play or queue a whole album on a player (fuzzy-matched name)
play_track	Play or queue one track
control_player	Pause, resume, stop, volume

Configuration

Env var	Default
LMS_URL	required	LMS base URL (no auth), e.g. http://lms.local:9000
PORT	3000	HTTP listen port
HISTORY_FILE	./data/history.jsonl	Play-history store
POLL_INTERVAL_MS	30000	Player status poll interval

Malformed values fail at startup rather than silently misbehaving.

Run locally

npm install
npm test        # unit + transport integration tests (vitest)
npm run bdd     # BDD scenarios (cucumber) - full stack against a stub LMS, no real server needed
LMS_URL=http://<lms-host>:9000 npm run smoke   # read-only checks against the real LMS
LMS_URL=http://<lms-host>:9000 npm run dev
claude mcp add --transport http lms http://localhost:3000/mcp

The BDD suite in features/ is the end-to-end check: real MCP client, real HTTP transport, real play recorder, against the stateful stub in test/stub/lms-stub.ts. Nothing there touches the real server, so playback scenarios are safe to run any time. npm run smoke is the only thing that talks to the real LMS, and it never sends playback commands.

Docker

docker compose up --build

CI (GitHub Actions) runs the test suites and pushes ghcr.io/sixeyed/lms-mcp-server with latest and sha-* tags on every push to main. No registry secrets needed - it authenticates with the workflow's GITHUB_TOKEN.

Deployment

Notes for running on Kubernetes (or any orchestrator):

• Image: ghcr.io/sixeyed/lms-mcp-server (public package).
• LMS_URL must be set - the server refuses to start without it.
• Single replica (strategy: Recreate) - the play-history poller must not run twice or plays are double-recorded.
• RWO persistent volume mounted at /data for the history file.
• Probes: liveness GET /healthz, readiness GET /readyz.

Clients

• Claude Code (LAN): claude mcp add --transport http lms http://<host>:3000/mcp; if you serve it over HTTPS with a private CA, set NODE_EXTRA_CA_CERTS.
• Claude Desktop: custom connectors are proxied through Anthropic's cloud so a LAN-only server is unreachable - use a local stdio bridge in claude_desktop_config.json:

  { "mcpServers": { "lms": { "command": "npx", "args": ["mcp-remote", "http://<host>:3000/mcp", "--allow-http"] } } }
  

• Claude iPhone app: not supported - would need public HTTPS exposure, and this server has no auth.