mcp-lyricscom

lyrics.com is a large public catalogue of song lyrics.

It files a song under its title, its artist, the album it appeared on and the

year, and it holds the words themselves. Its search reaches inside those words.

This server connects a chat client to that catalogue. You can search for a song

by a line you remember, search by title and artist, and read the words of one

song, a slice at a time, with the words you were looking for located in the text.

It needs no API key and no account.

_Version française_

Install

One-click install

Claude Code

claude mcp add lyricscom -- npx -y mcp-lyricscom

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

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

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

With Docker

{
  "mcpServers": {
    "lyricscom": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lyricscom: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

`www.lyrics.com`, and nothing else: no volume, no port, no credential.

Bundle, without npm

Download `mcp-lyricscom-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

• "Which song goes 'I've got a hand for you'?"
• "Find me the lyrics of Wichita Lineman by Glen Campbell."
• "Read me the second half of those words."
• "Where does the word 'lineman' appear in that song?"
• "What albums is that song on?"

The ordinary path runs from a search to a reading: a row carries an `id`, and

`get_lyrics` takes that id.

Tools

`search_lyrics`

Finds a song from words inside its lyrics. The site ranks loosely, so a match is

checked before it is served.

`verify` decides what a row is worth. `snippet` checks the excerpt the site

already returned and costs nothing. `full` fetches up to five song pages and

checks the complete words, which is slow and can bring on rate limiting. `none`

serves what the site ranked, unchecked.

In return: rows carrying `id`, which `get_lyrics` takes; `title`; `artist`;

`album` and `year`, `null` where the catalogue states none; `source_url`; and

`excerpt`, the matching line. `raw_result_count` is what the site returned and

`filtered_out` how many rows the check removed, so the two together say how loose

the ranking was. `has_more` and `next_page` continue.

`search_songs`

Finds songs by title, narrowed by artist.

In return: the rows `search_lyrics` returns, with `artist_filter` echoing

what was asked for and `filtered_out` counting what the artist restriction

removed. `strict` keeps the artists whose name matches as written; `loose`

accepts a name written differently.

`get_lyrics`

Reads the words of one song. Long lyrics are served a slice at a time.

In return: `status`, reading `ok` or `no_lyrics` for a page the site holds

without words; `title`, `artist` and `source_url`; and `lyrics`, the slice

itself. The reading is described by `total_chars`, `returned_chars`, `offset`,

`next_offset` and `truncated`: pass `next_offset` back to read on, and `null`

there means the end. `line_count` counts the lines of the slice, and `highlight`

answers for each word whether it was `found` and on which `line_number`, which is

`null` when it was not.

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.

On the User-Agent. This server names the project and links to its repository,

and the site serves that. It does refuse some generic tool agents outright: a

plain `curl` gets a 403. A `blocked_user_agent` error means the identity was

refused, and `LYRICSCOM_USER_AGENT` lets you set one of your choosing. What you

put there is your call and your responsibility.

Errors

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

naming the next move.

`throttled` and `blocked_user_agent` are this server's two names for a refusal to

serve, and a caller reading several sources normalises them onto whatever it

calls rate limiting.

As a library

The layer reading the site is published on its own, with its pacing, its cache

and its errors, and with no protocol attached.

import { LyricsComClient } from "mcp-lyricscom/client";

const client = new LyricsComClient();
const { data, cached } = await client.getSong({ id: "1234567" });
console.log(data.title, data.artist, cached);

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

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

well.

Pacing and attribution

Requests go out one at a time with at least a second between them, and the floor

of half a second holds however the server is configured. A `verify: "full"`

search fetches up to five song pages, which is the most expensive thing this

server does.

Every result carries the artist, the title and the address of the song page. Song

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

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

This MCP server is an unofficial project, with no affiliation to lyrics.com.

Privacy

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

on your machine, contacts `www.lyrics.com` 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

site 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.

mcp-lyricscom (français)

_English version_

lyrics.com est un grand catalogue public de paroles de

chansons. Il classe une chanson sous son titre, son artiste, l'album où elle a

paru et l'année, et il contient les paroles elles-mêmes. Sa recherche va à

l'intérieur de ces paroles.

Ce serveur relie un client de conversation à ce catalogue. On peut y chercher une

chanson par un vers dont on se souvient, chercher par titre et par artiste, et

lire les paroles d'une chanson par tranches, avec les mots cherchés localisés

dans le texte. Aucune clé d'API, aucun compte.

Installation

Installation en un clic

Claude Code

claude mcp add lyricscom -- npx -y mcp-lyricscom

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

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

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

renseigner.

Avec Docker

{
  "mcpServers": {
    "lyricscom": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lyricscom: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 `www.lyrics.com`, et de rien d'autre : aucun volume, aucun port,

aucun identifiant.

Bundle, sans npm

Téléchargez `mcp-lyricscom-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

• « Quelle est la chanson qui dit "I've got a hand for you" ? »
• « Trouve-moi les paroles de Wichita Lineman par Glen Campbell. »
• « Lis-moi la seconde moitié de ces paroles. »
• « Où apparaît le mot "lineman" dans cette chanson ? »
• « Sur quels albums cette chanson figure-t-elle ? »

Le chemin ordinaire va d'une recherche à une lecture : une ligne porte un `id`,

et `get_lyrics` reprend cet identifiant.

Les outils

`search_lyrics`

Trouve une chanson à partir de mots contenus dans ses paroles. Le site classe

largement, donc une correspondance est vérifiée avant d'être servie.

`verify` décide de ce que vaut une ligne. `snippet` vérifie l'extrait que le site

a déjà rendu et ne coûte rien. `full` va chercher jusqu'à cinq pages de chansons

et vérifie les paroles entières, ce qui est lent et peut déclencher une

limitation. `none` sert ce que le site a classé, sans vérification.

En retour : des lignes portant `id`, que `get_lyrics` reprend ; `title` ;

`artist` ; `album` et `year`, `null` là où le catalogue n'indique rien ;

`source_url` ; et `excerpt`, le vers correspondant. `raw_result_count` est ce que

le site a rendu et `filtered_out` le nombre de lignes que la vérification a

retirées, si bien que les deux ensemble disent à quel point le classement était

large. `has_more` et `next_page` poursuivent.

`search_songs`

Trouve des chansons par titre, resserrées par artiste.

En retour : les lignes que rend `search_lyrics`, avec `artist_filter` qui

redonne ce qui a été demandé et `filtered_out` qui compte ce que la restriction

sur l'artiste a retiré. `strict` garde les artistes dont le nom correspond tel

qu'écrit ; `loose` accepte un nom écrit autrement.

`get_lyrics`

Lit les paroles d'une chanson. Des paroles longues sont servies par tranches.

En retour : `status`, valant `ok` ou `no_lyrics` pour une page que le site

contient sans paroles ; `title`, `artist` et `source_url` ; et `lyrics`, la

tranche elle-même. La lecture est décrite par `total_chars`, `returned_chars`,

`offset`, `next_offset` et `truncated` : redonnez `next_offset` pour poursuivre,

et `null` marque la fin. `line_count` compte les lignes de la tranche, et

`highlight` répond pour chaque mot s'il a été `found` et à quel `line_number`,

`null` quand il ne l'a pas été.

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.

À propos du User-Agent. Ce serveur nomme le projet et renvoie vers son dépôt,

et le site le sert. Il refuse en revanche certains agents d'outils génériques :

un `curl` nu reçoit un 403. Une erreur `blocked_user_agent` signifie que

l'identité envoyée a été refusée, et `LYRICSCOM_USER_AGENT` permet d'en poser une

de votre choix. Ce que vous y mettez relève de votre décision et de votre

responsabilité.

Erreurs

Chaque échec porte un de ces codes, un message, et quand cela aide une indication

du geste suivant.

`throttled` et `blocked_user_agent` sont les deux noms que ce serveur donne à un

refus de servir, et un appelant qui lit plusieurs sources les ramène sur ce qu'il

appelle une limitation de débit.

Comme bibliothèque

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

erreurs, sans protocole attaché.

import { LyricsComClient } from "mcp-lyricscom/client";

const client = new LyricsComClient();
const { data, cached } = await client.getSong({ id: "1234567" });
console.log(data.title, data.artist, cached);

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

portant un des codes ci-dessus. Le plancher entre deux requêtes tient également

ici.

Rythme et attribution

Les requêtes partent une à une avec au moins une seconde entre elles, et le

plancher d'une demi-seconde tient quelle que soit la configuration. Une recherche

en `verify: "full"` va chercher jusqu'à cinq pages de chansons, ce qui est la

chose la plus coûteuse que fait ce serveur.

Chaque résultat porte l'artiste, le titre et l'adresse de la page de la chanson.

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 et n'écrit rien

sur le disque.

Ce MCP est un projet non officiel, sans affiliation à lyrics.com.

Confidentialité

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

votre machine, ne joint que `www.lyrics.com`, 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 site 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.