mcp-lrclib

mcp-lrclib

An MCP server for LRCLIB.Search tracks and read their lyrics, including time-synced (LRC) lyrics with atimestamp on every line. No API key, no account, no configuration.

(Version française plus bas / French version below)

Quickstart

Claude Code

claude mcp add lrclib -- npx -y mcp-lrclib

Claude Desktop, Cursor, and any client using the standard config format

{
  "mcpServers": {
    "lrclib": {
      "command": "npx",
      "args": ["-y", "mcp-lrclib"]
    }
  }
}

Tools

Search returns an LRCLIB id for every result; get_lyrics takes that id. That isthe intended chain: search, then read.

The server is read-only. It never contributes lyrics back to LRCLIB.

Things worth knowing

Search results never carry lyrics. LRCLIB embeds the full plain and syncedlyrics in every row of a search response, which makes one search worth roughly29,000 tokens. This server strips them, bringing the same 20 results down to about800 tokens. Fetch the text you actually want with get_lyrics.

Time-synced lyrics are the point. format: "synced" returns the raw LRC blockplus a parsed list of {time_seconds, text} entries, ready to drive a karaokedisplay or line up with audio. Check has_synced_lyrics in the search resultsfirst: not every track has them.

Duration and album disambiguate versions. LRCLIB holds several entries for thesame song across releases and re-recordings. Pass duration_seconds andalbum_name to pin the right one, or use the id from search and skip thequestion entirely.

Instrumental tracks are an answer. They come back with status: "instrumental"as a successful result with no text, so there is nothing to retry.

LRCLIB searches metadata, not lyrics. It cannot find a song from a word insideits lyrics. For that, see mcp-lyricscom,which covers exactly that case.

Configuration

Every variable is optional. Set them in the env block of your MCP client config.

LRCLIB asks third-party clients to identify themselves with a name, a version and aproject link, which the default User-Agent does. Please keep that shape if youoverride it.

How it works

LRCLIB offers a real public JSON API, so this server makes plain HTTP calls tohttps://lrclib.net/api and maps the responses. It sends one request at a time,paces itself, backs off when rate limited, and keeps a small in-memory cache. Asearch already returns the lyrics of every result, so a get_lyrics call rightafter a search is usually served from cache with no second request.

Development

npm install
npm run build:fixtures   # regenerate the JSON test fixtures
npm test                 # unit tests, no network
npm run typecheck
npm run build
LRCLIB_LIVE=1 npm run test:live   # hits the real API, excluded from CI
npm run inspector        # explore the tools in the MCP Inspector

Fixtures are generated, not captured: they reproduce LRCLIB's field names andshapes with placeholder text, so the tests are deterministic and no copyrightedlyrics live in this repository.

The API layer (src/lrclib, src/text) does not import the MCP SDK and ispublished separately as mcp-lrclib/client, so it can be used as a plain library.

Lyrics and copyright

Song lyrics are copyrighted works owned by their authors and publishers. Thisproject claims no rights over them, and neither the lyrics nor any database ofthem ships with it.

This server is a client for LRCLIB's public API, which LRCLIB provides free ofcharge and explicitly invites third-party clients to use. It requests data ondemand, one call at a time, in response to an explicit request from you or yourassistant. It writes nothing to disk and contributes nothing back to LRCLIB.

Every result carries the artist, the title and a source URL. If you display orreuse anything this server returns, keep that attribution and link back to thesource.

This is an unofficial project, with no affiliation to or endorsement by LRCLIB.

License

MIT. See LICENSE. The license covers this source code only, not thelyrics retrieved through it.

mcp-lrclib (français)

Un serveur MCP pour LRCLIB.Cherchez des morceaux et lisez leurs paroles, y compris les paroles synchronisées(LRC), horodatées ligne par ligne. Sans clé d'API, sans compte, sans configuration.

Démarrage rapide

Claude Code

claude mcp add lrclib -- npx -y mcp-lrclib

Claude Desktop, Cursor, et tout client utilisant le format standard

{
  "mcpServers": {
    "lrclib": {
      "command": "npx",
      "args": ["-y", "mcp-lrclib"]
    }
  }
}

Outils

La recherche renvoie un id LRCLIB pour chaque résultat, et get_lyrics prend cetid. C'est l'enchaînement prévu : chercher, puis lire.

Le serveur est en lecture seule. Il ne contribue jamais de paroles à LRCLIB.

Ce qu'il faut savoir

Les résultats de recherche ne contiennent jamais de paroles. LRCLIB embarque lesparoles complètes, simples et synchronisées, dans chaque ligne de résultat, ce quiporte une seule recherche à environ 29 000 tokens. Ce serveur les retire, ramenantles mêmes 20 résultats à environ 800 tokens. Le texte se récupère ensuite avecget_lyrics.

Les paroles synchronisées sont l'intérêt principal. format: "synced" renvoiele bloc LRC brut et une liste analysée de {time_seconds, text}, directementexploitable pour du karaoké ou un calage sur l'audio. Vérifiez d'abordhas_synced_lyrics dans les résultats : tous les morceaux n'en ont pas.

Durée et album départagent les versions. LRCLIB conserve plusieurs entrées pourun même titre selon les éditions et réenregistrements. Passez duration_seconds etalbum_name pour viser la bonne, ou utilisez l'id issu de la recherche.

Un morceau instrumental est une réponse. Il revient en status: "instrumental",résultat réussi et sans texte : inutile de réessayer.

LRCLIB cherche dans les métadonnées, pas dans les paroles. Il ne sait pasretrouver une chanson à partir d'un mot du texte. Pour cela, voyezmcp-lyricscom, qui couvre exactement cebesoin.

Configuration

Toutes les variables sont optionnelles, à déclarer dans le bloc env de votre client.

LRCLIB demande aux clients tiers de s'identifier par un nom, une version et un lienvers le projet, ce que fait le User-Agent par défaut. Merci d'en conserver la formesi vous le remplacez.

Fonctionnement

LRCLIB expose une véritable API JSON publique. Ce serveur fait donc de simplesappels HTTP vers https://lrclib.net/api et transpose les réponses. Il envoie unerequête à la fois, s'impose un rythme, ralentit en cas de limitation et garde unpetit cache mémoire. Comme la recherche rapporte déjà les paroles de chaquerésultat, un get_lyrics juste après est généralement servi depuis le cache, sansseconde requête.

Développement

npm install
npm run build:fixtures   # régénère les fixtures JSON de test
npm test                 # tests unitaires, sans réseau
npm run typecheck
npm run build
LRCLIB_LIVE=1 npm run test:live   # touche la vraie API, exclu de la CI
npm run inspector        # explorer les outils dans le MCP Inspector

Les fixtures sont générées, pas capturées : elles reproduisent les noms de champs etles formes de LRCLIB avec du texte de remplissage, ce qui rend les testsdéterministes et évite de stocker des paroles sous droits dans ce dépôt.

La couche API (src/lrclib, src/text) n'importe pas le SDK MCP et est publiéeséparément sous mcp-lrclib/client, utilisable comme simple bibliothèque.

Paroles et droits d'auteur

Les paroles de chansons sont des œuvres protégées, propriété de leurs auteurs etéditeurs. Ce projet ne revendique aucun droit dessus, et n'embarque ni paroles nibase de paroles.

Ce serveur est un client de l'API publique de LRCLIB, service gratuit qui inviteexplicitement les clients tiers à l'utiliser. Il demande les données à la demande,un appel à la fois, en réponse à une demande explicite de votre part ou de celle devotre assistant. Il n'écrit rien sur le disque et ne contribue rien à LRCLIB.

Chaque résultat porte l'artiste, le titre et une URL source. Si vous affichez ouréutilisez ce que renvoie ce serveur, conservez cette attribution et le lien vers lasource.

Projet non officiel, sans affiliation à LRCLIB ni approbation de sa part.

Licence

MIT, voir LICENSE. La licence couvre uniquement le code source, pas lesparoles récupérées par son intermédiaire.