Purpose
mcp-lrclib is an MCP (Model Context Protocol) server that connects to the LRCLIB lyrics database, allowing chat clients to search for songs and read lyrics. LRCLIB is a free and open lyrics database, built collaboratively by its users, and can be used without a key or account. The database contains two forms of lyrics: plain-text lyrics, and LRC-format lyrics where each line carries a singing timestamp, the latter being suitable for karaoke display or lyric-panel following. Tracks are archived by their title, artist, album, and duration, so different releases of the same song are stored side by side.
Main capabilities
The server provides the following capabilities:
- Search for tracks by title, artist, or album, supporting free-text search or field-based search.
- Read the plain-text lyrics of a song.
- Read timestamped synchronized lyric lines.
- Check the metadata of a release before reading its lyrics.
Note that LRCLIB archives tracks by metadata, so search locates songs by title, artist, or album, and a word remembered from within a song cannot be found through search.
Tool descriptions
search_tracks: Finds tracks whose metadata matches, supporting either a single free-text search or a field-based search. Multiple releases of the same song are returned side by side and can be distinguished by album and duration. The input parameter is query or one of the three fields. The returned content includes: id (for use with get_lyrics and get_track), track_name, artist_name, album_name, duration_seconds (used to distinguish different releases of the same song), instrumental, has_plain_lyrics and has_synced_lyrics (which can be checked before requesting synced lyrics), source_url, as well as result_count and total_available (the number of tracks LRCLIB provides before applying limit). If a track was archived without an album or duration, the corresponding field is null. Search result rows do not include lyric content and must be read via get_lyrics.
get_lyrics: Reads the lyrics of a track, which can be plain text or LRC lines with a singing timestamp for each line. Long lyrics are returned in chunks, truncated at line boundaries. The returned content includes: status (ok, instrumental means no lyrics to sing, no_lyrics means no lyrics at archive time), track (including id, title, artist, album, duration, and source_url), plain_lyrics, synced_lyrics (raw LRC text), and synced_lines (a list of { time_seconds, text }), and when the shard is truncated there will be synced_lines_truncated. The read status is described by paginated_form, total_chars, returned_chars, offset, next_offset, and truncated: pass next_offset back to continue reading, and null means the end has been reached. attribution is the line that should be cited when displaying lyrics. If status is instrumental, that is the complete answer.
get_track: reads the metadata of a track by id, without reading lyrics. Use it to confirm a release before requesting lyrics, or to resolve an id passed from a previous conversation. The return content includes: track (containing the fields carried by the search row), and duration_formatted (m:ss format, or null if there is no duration at archive time). has_plain_lyrics and has_synced_lyrics indicate which forms get_lyrics can provide.
Usage
One-click installation
Supports Claude Desktop, Cursor, and any client that uses the standard configuration format. Requires Node 24 or later, and no environment variables need to be set.
Configuration notes: -i keeps standard input open (the protocol transport channel), and -t is not set because a TTY rewrites the stream. The container needs outbound HTTPS access to lrclib.net and nothing else: no volumes, ports, or credentials are needed.
Bundle installation (no npm required)
Download mcp-lrclib-2.0.1.mcpb from the latest release and open it. Clients that support MCP bundles install it automatically, with no npm and no configuration file editing. The bundle includes its own dependencies, and nothing is downloaded during installation.
Example requests you can make
- “Find me the lyrics of Le Sud by Nino Ferrer.”
- “Give me the timed lyrics of Bohemian Rhapsody so I can follow along.”
- “Which version of Hallelujah is on LRCLIB, and how long is each one?”
- “Read me the second half of those lyrics.”
- “Does track 3396226 have synced lyrics?”
The usual path is from search to reading: search_tracks gives an id, and get_lyrics uses that id.
Configuration
Every variable is optional and is set in the env block of the client configuration. Values outside the range fall back to defaults, and the reason is written to stderr.
When to use it
Suitable for scenarios that require searching for songs and reading plain text or synced lyrics in a chat client or MCP-compatible client, such as following karaoke display, viewing lyrics, confirming information about a release, and so on.
Limitations
- Search is done only through metadata such as title, artist, or album, and cannot search by words in the lyrics content.
- Requires Node 24 or later.
- The container needs outbound HTTPS access to lrclib.net.
- This project is unofficial and is not affiliated with LRCLIB.
- Lyrics belong to their authors and publishers; the project claims no rights, does not include a lyrics database, does not write to disk, and does not send content back to LRCLIB.
Error handling
Each failure carries one of six codes, a message, and, when helpful, a hint for the next action.
Using as a library
The layer that reads LRCLIB can be published separately, with its rate control, caching, and error handling, without the protocol. search, get, and getById each return { data, cached } and throw errors carrying one of six codes. The minimum interval between two requests also applies here.
Pace and attribution
Requests are issued one by one, with a minimum interval between them, which remains unchanged no matter how the server configures that lower bound. The User-Agent always ends with the project identifier and an address where a person can be contacted. LRCLIB is a free service, publicly releasedIts API is machine-readable, and the server calls it on demand one at a time to respond to your requests.
Each result carries the artist, title, and its LRCLIB page address, and get_lyrics carries attribution; write these three on one line.
Privacy
The server does not collect any information about you, nor does it send anything to its author. It runs on your machine, contacts only lrclib.net, keeps answers in memory while running, and does not write to disk. PRIVACY.md explains what requests carry and which settings change these.
Testing
Tests run against generated fixed data and do not make network requests. The live test suite npm run test:live makes one request to each route and runs nightly against the service itself.
License
MIT, see LICENSE. Lyrics belong to their authors and publishers, and the database belongs to LRCLIB and its contributors.
