mcp-lyricscom

An MCP server for lyrics.com. Search songs by a word in their lyrics, by title, and read the full text. No API key, no account, no configuration.

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

Quickstart

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

That is the whole setup. There is nothing to sign up for.

Tools

The two search tools return a lyrics.com id for every result; get_lyrics takes that id. That is the intended chain: search, then read.

Things worth knowing

Search really checks the lyrics. lyrics.com's own search also returns title matches and loose matches. search_lyrics filters them out locally, using a word-boundary matcher, so a result is a song where the word genuinely appears. coup does not match beaucoup, but enfant does match enfants. Set verify: "none" to see the raw, unfiltered list.

Pagination is yours to drive. One call fetches one page (24 rows on lyrics.com). The response carries has_more and next_page. Raising limit does not fetch more pages, on purpose: chaining several fetches inside a single tool call is the fastest way to get rate limited.

Some songs have no lyrics. A valid lyrics.com page can simply have no text on file. That comes back as status: "no_lyrics" with a successful result, not an error, so there is nothing to retry.

Rate limiting is visible, not silent. lyrics.com answers a throttled request with an empty body rather than a normal error code. This server detects that and returns an explicit throttled error telling you to wait and try again. It never reports throttling as "no results found", which would be indistinguishable from a genuine answer.

Configuration

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

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

About the User-Agent

This server identifies itself honestly by default, naming the project and linking to this repository. lyrics.com serves that fine today.

It does block some generic tool agents outright: a plain curl/8.5.0 gets a 403. If you ever see a blocked_user_agent error, set LYRICSCOM_USER_AGENT to a value of your choosing. That override exists so you are not stuck, and what you put in it is your call and your responsibility.

Troubleshooting

"throttled" errors. lyrics.com is rate limiting you. The server already retries with backoff and slows itself down on its own, so seeing this error means those retries were exhausted. Once the site starts throttling, the window commonly lasts several minutes, not seconds: wait a minute or more before trying again, and raise LYRICSCOM_MIN_INTERVAL_MS if it keeps happening. A throttled error does not mean your query has no results.

"blocked_user_agent" errors. See the User-Agent section above.

"parse_failure" errors. lyrics.com changed its page layout and the server could not read the response. Please open an issue with the query you used. The server deliberately reports this loudly instead of pretending it found nothing.

Empty results. If raw_result_count is greater than zero while results is empty, lyrics.com did return rows but none of them actually contain your word. Try verify: "none" to see them anyway.

How it works

There is no lyrics.com API. The server requests the same public pages you would open in a browser and reads them with cheerio. It fetches one page at a time, roughly one request per second, backs off when the site pushes back, and keeps a small in-memory cache so repeated questions about the same song do not hit the site again.

Development

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

The fixtures are generated, not scraped: they reproduce lyrics.com's markup structure with placeholder text, so the parser tests are deterministic and no copyrighted lyrics live in this repository.

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

Lyrics and copyright

Song lyrics are copyrighted works owned by their authors and publishers. This project claims no rights over them.

This server is a client. It fetches the same public lyrics.com pages you could open in a browser, on demand, one request at a time, in response to an explicit request from you or your assistant. It does not crawl the site, does not build a lyrics database, and does not write anything to disk. Pages are held in memory for a few minutes so that repeated questions do not hit the site again.

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

The server honours lyrics.com's robots.txt: none of the endpoints it uses are disallowed there, and it paces itself to roughly one request per second. That pacing is enforced: LYRICSCOM_MIN_INTERVAL_MS is refused below 500 ms, and a lower value falls back to the standard interval with a warning on stderr. Raise it to slow the client down further.

This is an unofficial project, with no affiliation to, endorsement by, or sponsorship from lyrics.com or STANDS4 Ltd. Use it in accordance with lyrics.com's terms of service and the copyright law that applies to you.

License

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

mcp-lyricscom (français)

Un serveur MCP pour lyrics.com. Cherchez des chansons par un mot présent dans les paroles, par titre, et lisez le texte complet. Sans clé d'API, sans compte, sans configuration.

Démarrage rapide

Installation en un clic

Claude Code

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

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

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

C'est toute l'installation. Il n'y a aucune inscription.

Outils

Les deux outils de recherche renvoient un id lyrics.com pour chaque résultat, et get_lyrics prend cet id. C'est l'enchaînement prévu : chercher, puis lire.

Ce qu'il faut savoir

La recherche vérifie vraiment les paroles. La recherche de lyrics.com renvoie aussi des correspondances de titre et des à-peu-près. search_lyrics les écarte localement, avec un matcher qui respecte les frontières de mot : un résultat est donc une chanson où le mot est réellement présent. coup ne matche pas beaucoup, mais enfant matche bien enfants. Mettez verify: "none" pour voir la liste brute.

C'est vous qui paginez. Un appel récupère une page (24 lignes chez lyrics.com). La réponse porte has_more et next_page. Augmenter limit ne va pas chercher plus de pages, volontairement : enchaîner plusieurs requêtes dans un seul appel d'outil est le meilleur moyen de se faire limiter.

Certaines chansons n'ont pas de paroles. Une page lyrics.com valide peut simplement n'avoir aucun texte enregistré. Cela revient en status: "no_lyrics" avec un résultat réussi, pas une erreur : inutile de réessayer.

La limitation de débit est visible, pas silencieuse. lyrics.com répond à une requête limitée par un corps vide plutôt que par un code d'erreur normal. Ce serveur le détecte et renvoie une erreur throttled explicite, qui vous dit d'attendre et de réessayer. Il ne présente jamais une limitation comme « aucun résultat », ce qui serait indiscernable d'une vraie réponse.

Configuration

Toutes les variables sont optionnelles. Elles se déclarent dans le bloc env de la configuration de votre client MCP.

À propos du User-Agent

Le serveur s'identifie honnêtement par défaut, en nommant le projet et en pointant vers ce dépôt. lyrics.com l'accepte sans problème aujourd'hui.

Le site bloque en revanche certains agents d'outils génériques : un simple curl/8.5.0 reçoit un 403. Si vous voyez une erreur blocked_user_agent, définissez LYRICSCOM_USER_AGENT à la valeur de votre choix. Cette surcharge existe pour que vous ne restiez pas bloqué ; ce que vous y mettez relève de votre décision et de votre responsabilité.

Dépannage

Erreurs « throttled ». lyrics.com vous limite. Le serveur réessaie déjà avec backoff et ralentit tout seul : voir cette erreur signifie que ces tentatives ont été épuisées. Une fois la limitation déclenchée, la fenêtre dure couramment plusieurs minutes, pas quelques secondes : attendez une minute ou plus avant de réessayer, et augmentez LYRICSCOM_MIN_INTERVAL_MS si cela persiste. Une erreur throttled ne signifie pas que votre requête n'a pas de résultats.

Erreurs « blocked_user_agent ». Voir la section User-Agent ci-dessus.

Erreurs « parse_failure ». lyrics.com a changé la structure de ses pages et le serveur n'a pas su lire la réponse. Merci d'ouvrir une issue en indiquant la requête utilisée. Le serveur signale volontairement ce cas au lieu de faire comme s'il n'avait rien trouvé.

Résultats vides. Si raw_result_count est supérieur à zéro alors que results est vide, lyrics.com a bien renvoyé des lignes mais aucune ne contient réellement votre mot. Essayez verify: "none" pour les voir quand même.

Fonctionnement

lyrics.com n'a pas d'API. Le serveur demande les mêmes pages publiques que celles que vous ouvririez dans un navigateur et les lit avec cheerio. Il récupère une page à la fois, à environ une requête par seconde, ralentit quand le site le lui demande, et garde un petit cache mémoire pour ne pas redemander deux fois la même page.

Développement

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

Les fixtures sont générées, pas aspirées : elles reproduisent la structure du markup de lyrics.com avec du texte de remplissage, ce qui rend les tests de parsing déterministes et évite de stocker des paroles sous droits dans ce dépôt.

La couche de scraping (src/lyricscom, src/text) n'importe pas le SDK MCP et est publiée séparément sous mcp-lyricscom/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.

Ce serveur est un client. Il va chercher les mêmes pages publiques de lyrics.com que celles que vous pourriez ouvrir dans un navigateur, à la demande, une requête à la fois, en réponse à une demande explicite de votre part ou de celle de votre assistant. Il ne parcourt pas le site, ne constitue aucune base de paroles, et n'écrit rien sur le disque. Les pages restent en mémoire quelques minutes pour ne pas solliciter le site inutilement.

Chaque résultat porte l'artiste, le titre et l'URL source. Si vous affichez ou réutilisez ce que renvoie ce serveur, conservez cette attribution et le lien vers la page d'origine.

Le serveur respecte le robots.txt de lyrics.com : aucun des endpoints qu'il utilise n'y est interdit, et il s'impose environ une requête par seconde. Ce rythme est contraint : LYRICSCOM_MIN_INTERVAL_MS est refusé en dessous de 500 ms, une valeur plus basse retombant sur l'intervalle standard avec un avertissement sur stderr. Augmentez-le pour ralentir davantage.

Projet non officiel, sans affiliation à lyrics.com ni à STANDS4 Ltd, ni approbation ou parrainage de leur part. Utilisez-le dans le respect des conditions d'utilisation de lyrics.com et du droit d'auteur qui vous est applicable.

Licence

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