mcp-lrclib

LRCLIB is a free, open database of song lyrics, built by

the people who use it and offered to anyone without a key or an account. It holds

two forms of the words: the plain text of a song, and the LRC form, where every

line carries the moment it is sung, which is what a karaoke display or a lyrics

panel follows along with. A track is filed there by its title, its artist, its

album and its duration, so the several releases of one song sit side by side.

This server connects a chat client to that database. You can search for a track

by title, artist or album, read the plain words of a song, read its time-synced

lines with their timestamps, and check the metadata of one release before

reading it. It needs no API key and no account.

_Version française_

Install

One-click install

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"]
    }
  }
}

Node 24 or later is required, and no environment variable has to be set.

With Docker

{
  "mcpServers": {
    "lrclib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lrclib:2.0.1"]
    }
  }
}

`-i` keeps stdin open, which is where the protocol travels, and `-t` is left out

because a TTY rewrites the stream. The container needs outbound HTTPS to

`lrclib.net`, and nothing else: no volume, no port, no credential.

Bundle, without npm

Download `mcp-lrclib-2.0.1.mcpb` from

the latest release and

open it. A client that supports MCP bundles installs it on its own, with no npm

and no configuration file to edit. The bundle carries its dependencies, so

nothing is fetched at install time.

What you can ask

• "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 ordinary path runs from a search to a reading: `search_tracks` names an `id`,

and `get_lyrics` takes that id.

Tools

LRCLIB files a track by its metadata, so a search reaches a song through its

title, its artist or its album. A word remembered from inside a song finds

nothing there.

`search_tracks`

Finds the tracks whose metadata matches, in one free-text search or in fields of

their own. Several releases of one song come back side by side, and their album

and duration tell them apart.

Pass `query`, or one of the three fields.

In return: rows carrying `id`, which `get_lyrics` and `get_track` take;

`track_name` and `artist_name`; `album_name` and `duration_seconds`, which tell

two releases of one song apart; `instrumental`; `has_plain_lyrics` and

`has_synced_lyrics`, so timed lines can be checked for before they are asked

for; and `source_url`. Alongside come `result_count` and `total_available`, the

tracks LRCLIB served before `limit` was applied. `album_name` and

`duration_seconds` are `null` on a track filed without them, and the rows carry

no words at all: `get_lyrics` reads those.

`get_lyrics`

Reads the words of one track, either as plain text or as LRC lines carrying the

moment each one is sung. Long lyrics are served a slice at a time, resuming at a

line boundary.

In return: `status`, which reads `ok`, `instrumental` for a track with no

words to sing, or `no_lyrics` for one filed without them; `track` with its id,

title, artist, album, duration and `source_url`; `plain_lyrics`; `synced_lyrics`

as raw LRC text and `synced_lines` as a list of `{ time_seconds, text }`, with

`synced_lines_truncated` when the slice cut them. The reading is described by

`paginated_form`, `total_chars`, `returned_chars`, `offset`, `next_offset` and

`truncated`: pass `next_offset` back to read on, and `null` there means the end.

`attribution` is the line to cite when the words are shown. A `status` of

`instrumental` is a complete answer.

`get_track`

Reads the metadata of one track from its id, leaving the words aside. It confirms

a release before the words are asked for, and it resolves an id carried over from

earlier in a conversation.

In return: `track`, holding the fields a search row carries, and

`duration_formatted` as `m:ss`, which is `null` when the track is filed without a

duration. `has_plain_lyrics` and `has_synced_lyrics` say which forms

`get_lyrics` can serve for it.

Configuration

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

A value outside its range falls back to the default, and the reason is written to

stderr.

Errors

Every failure carries one of six codes, a message, and where it helps a hint

naming the next move.

As a library

The layer reading LRCLIB is published on its own, with its pacing, its cache and

its errors, and with no protocol attached.

import { LrclibClient } from "mcp-lrclib/client";

const client = new LrclibClient();
const { data, cached } = await client.getById(3396226);
console.log(data.track_name, data.synced_lyrics !== null, cached);

`search`, `get` and `getById` each answer `{ data, cached }`, and throw an error

carrying one of the six codes. The floor between two requests holds here as well.

Pacing and attribution

Requests go out one at a time with a minimum gap between them, and that floor

holds however the server is configured. The `User-Agent` always ends with the

project identity and an address where a person can be reached. LRCLIB is a free

service and publishes its API for machines to read, and this server reads it on

demand, one call at a time, in answer to something you asked for.

Every result carries the artist, the title and the address of its LRCLIB page,

and `get_lyrics` carries `attribution`, the three of them written as one line.

Song lyrics are the work of their authors and publishers. This project claims no

rights over them, ships no database of them, writes nothing to disk, and

contributes nothing back to LRCLIB. This MCP server is an unofficial project,

with no affiliation to LRCLIB.

Privacy

This server collects nothing about you and sends nothing to its author. It runs

on your machine, contacts `lrclib.net` and nothing else, holds its answers in memory

while it runs, and writes nothing to disk.

PRIVACY.md states what a request carries and which settings change

any of it.

Development

npm install
npm run build:fixtures
npm test
npm run check

Tests run against generated fixtures and make no network request. The live suite,

`npm run test:live`, makes one request per route and runs nightly against the

service itself.

Contributing

Bugs, questions and ideas belong in

the issue tracker. Pull requests

are welcome; opening an issue first helps agree on the shape of the change. See

CONTRIBUTING.md.

License

MIT, see LICENSE. The lyrics belong to their authors and publishers,

and the database to LRCLIB and its contributors.

mcp-lrclib (français)

_English version_

LRCLIB est une base de paroles de chansons libre et

ouverte, alimentée par ceux qui s'en servent et offerte à tous sans clé ni

compte. Elle contient deux formes des paroles : le texte simple d'une chanson, et

la forme LRC, où chaque ligne porte le moment où elle est chantée, ce que suit un

affichage karaoké ou un panneau de paroles. Un titre y est classé par son nom,

son artiste, son album et sa durée, si bien que les différentes parutions d'une

même chanson y voisinent.

Ce serveur relie un client de conversation à cette base. On peut y chercher un

titre par son nom, son artiste ou son album, lire les paroles simples d'une

chanson, lire ses lignes horodatées avec leurs marques de temps, et vérifier la

fiche d'une parution avant de la lire. Aucune clé d'API, aucun compte.

Installation

Installation en un clic

Claude Code

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

Claude Desktop, Cursor, et tout client au format de configuration standard

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

Node 24 ou plus récent est nécessaire, et aucune variable d'environnement n'est à

renseigner.

Avec Docker

{
  "mcpServers": {
    "lrclib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lrclib:2.0.1"]
    }
  }
}

`-i` garde l'entrée standard ouverte, qui est le canal du protocole, et `-t` est

omis parce qu'un TTY réécrit le flux. Le conteneur a besoin d'un accès HTTPS

sortant vers `lrclib.net`, et de rien d'autre : aucun volume, aucun port, aucun

identifiant.

Bundle, sans npm

Téléchargez `mcp-lrclib-2.0.1.mcpb` depuis

la dernière publication

et ouvrez-le. Un client qui gère les bundles MCP l'installe seul, sans npm et

sans fichier de configuration à modifier. Le bundle emporte ses dépendances, donc

rien n'est téléchargé à l'installation.

Ce qu'on peut demander

• « Trouve-moi les paroles du Sud de Nino Ferrer. »
• « Donne-moi les paroles horodatées de Bohemian Rhapsody pour que je suive. »
• « Quelles versions de Hallelujah y a-t-il sur LRCLIB, et quelle est leur durée ? »
• « Lis-moi la seconde moitié de ces paroles. »
• « Est-ce que le titre 3396226 a des paroles synchronisées ? »

Le chemin ordinaire va d'une recherche à une lecture : `search_tracks` nomme un

`id`, et `get_lyrics` reprend cet identifiant.

Les outils

LRCLIB classe un titre par sa fiche, donc une recherche atteint une chanson par

son nom, son artiste ou son album. Un mot retenu de l'intérieur d'une chanson n'y

trouve rien.

`search_tracks`

Trouve les titres dont la fiche correspond, en une recherche libre ou par champs.

Plusieurs parutions d'une même chanson reviennent côte à côte, et leur album et

leur durée les distinguent.

Passez `query`, ou l'un des trois champs.

En retour : des lignes portant `id`, que `get_lyrics` et `get_track`

reprennent ; `track_name` et `artist_name` ; `album_name` et `duration_seconds`,

qui distinguent deux parutions d'une même chanson ; `instrumental` ;

`has_plain_lyrics` et `has_synced_lyrics`, qui permettent de vérifier l'existence

des lignes horodatées avant de les demander ; et `source_url`. Viennent aussi

`result_count` et `total_available`, les titres que LRCLIB a servis avant

l'application de `limit`. `album_name` et `duration_seconds` valent `null` sur un

titre classé sans eux, et les lignes ne portent aucune parole : `get_lyrics` les

lit.

`get_lyrics`

Lit les paroles d'un titre, en texte simple ou en lignes LRC portant le moment où

chacune est chantée. Des paroles longues sont servies par tranches, coupées sur

une fin de ligne.

En retour : `status`, qui vaut `ok`, `instrumental` pour un titre sans

paroles à chanter, ou `no_lyrics` pour un titre classé sans elles ; `track` avec

son identifiant, son nom, son artiste, son album, sa durée et son `source_url` ;

`plain_lyrics` ; `synced_lyrics` en texte LRC brut et `synced_lines` en liste de

`{ time_seconds, text }`, avec `synced_lines_truncated` quand la tranche les a

coupées. La lecture est décrite par `paginated_form`, `total_chars`,

`returned_chars`, `offset`, `next_offset` et `truncated` : redonnez `next_offset`

pour poursuivre, et `null` marque la fin. `attribution` est la ligne à citer

quand les paroles sont montrées. Un `status` à `instrumental` est une réponse

complète.

`get_track`

Lit la fiche d'un titre depuis son identifiant, sans les paroles. Elle confirme

une parution avant qu'on demande les paroles, et elle résout un identifiant venu

d'un échange précédent.

En retour : `track`, qui porte les champs d'une ligne de recherche, et

`duration_formatted` sous la forme `m:ss`, `null` pour un titre classé sans

durée. `has_plain_lyrics` et `has_synced_lyrics` disent quelles formes

`get_lyrics` peut servir.

Configuration

Chaque variable est facultative. Elles se posent dans le bloc `env` de la

configuration du client.

Une valeur hors de sa plage retombe sur le défaut, et la raison est écrite sur la

sortie d'erreur.

Erreurs

Chaque échec porte un des six codes, un message, et quand cela aide une

indication du geste suivant.

Comme bibliothèque

La couche qui lit LRCLIB est publiée seule, avec son rythme, son cache et ses

erreurs, sans protocole attaché.

import { LrclibClient } from "mcp-lrclib/client";

const client = new LrclibClient();
const { data, cached } = await client.getById(3396226);
console.log(data.track_name, data.synced_lyrics !== null, cached);

`search`, `get` et `getById` répondent chacun `{ data, cached }`, et lèvent une

erreur portant un des six codes. Le plancher entre deux requêtes tient également

ici.

Rythme et attribution

Les requêtes partent une à une avec un écart minimal entre elles, et ce plancher

tient quelle que soit la configuration. Le `User-Agent` se termine toujours par

l'identité du projet et une adresse où joindre une personne. LRCLIB est un

service gratuit et publie son API pour être lue par des machines, et ce serveur

la lit à la demande, un appel à la fois, en réponse à ce que vous avez demandé.

Chaque résultat porte l'artiste, le titre et l'adresse de sa page LRCLIB, et

`get_lyrics` porte `attribution`, ces trois éléments écrits en une ligne.

Les paroles sont l'œuvre de leurs auteurs et de leurs éditeurs. Ce projet ne

revendique aucun droit dessus, n'embarque aucune base de paroles, n'écrit rien

sur le disque et ne contribue rien à LRCLIB. Ce MCP est un projet non officiel,

sans affiliation à LRCLIB.

Confidentialité

Ce serveur ne collecte rien sur vous et n'envoie rien à son auteur. Il tourne sur

votre machine, ne joint que `lrclib.net`, garde ses réponses en mémoire le temps qu'il

tourne, et n'écrit rien sur le disque. PRIVACY.md dit ce qu'une

requête emporte et quels réglages changent cela.

Développement

npm install
npm run build:fixtures
npm test
npm run check

Les tests s'exécutent sur des fixtures engendrées et n'émettent aucune requête.

La suite en direct, `npm run test:live`, émet une requête par route et tourne

chaque nuit contre le service lui-même.

Contribuer

Les anomalies, les questions et les idées ont leur place dans

le suivi d'incidents. Les

propositions de modification sont bienvenues ; ouvrir un ticket d'abord aide à

s'accorder sur la forme du changement. Voir CONTRIBUTING.md.

Licence

MIT, voir LICENSE. Les paroles appartiennent à leurs auteurs et à

leurs éditeurs, et la base à LRCLIB et à ses contributeurs.