mcp-lyricscom

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

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 titlematches and loose matches. search_lyrics filters them out locally, using aword-boundary matcher, so a result is a song where the word genuinely appears.coup does not match beaucoup, but enfant does match enfants. Setverify: "none" to see the raw, unfiltered list.

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

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

Rate limiting is visible, not silent. lyrics.com answers a throttled requestwith an empty body rather than a normal error code. This server detects that andreturns an explicit throttled error telling you to wait and try again. It neverreports throttling as "no results found", which would be indistinguishable from agenuine 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 linkingto 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 avalue of your choosing. That override exists so you are not stuck, and what youput in it is your call and your responsibility.

Troubleshooting

"throttled" errors. lyrics.com is rate limiting you. The server alreadyretries with backoff and slows itself down on its own, so seeing this error meansthose retries were exhausted. Once the site starts throttling, the windowcommonly lasts several minutes, not seconds: wait a minute or more before tryingagain, and raise LYRICSCOM_MIN_INTERVAL_MS if it keeps happening. A throttlederror 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 servercould not read the response. Please open an issuewith the query you used. The server deliberately reports this loudly instead ofpretending it found nothing.

Empty results. If raw_result_count is greater than zero while results isempty, 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 wouldopen in a browser and reads them with cheerio. Itfetches one page at a time, roughly one request per second, backs off when thesite pushes back, and keeps a small in-memory cache so repeated questions aboutthe 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 markupstructure with placeholder text, so the parser tests are deterministic and nocopyrighted lyrics live in this repository.

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

Lyrics and copyright

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

This server is a client. It fetches the same public lyrics.com pages you couldopen in a browser, on demand, one request at a time, in response to an explicitrequest from you or your assistant. It does not crawl the site, does not build alyrics database, and does not write anything to disk. Pages are held in memoryfor 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 orreuse anything this server returns, keep that attribution and link back to thesource page.

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

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

License

MIT. See LICENSE. The license covers this source code only, not thelyrics 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 letexte complet. Sans clé d'API, sans compte, sans configuration.

Démarrage rapide

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, etget_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 renvoieaussi des correspondances de titre et des à-peu-près. search_lyrics les écartelocalement, avec un matcher qui respecte les frontières de mot : un résultat estdonc une chanson où le mot est réellement présent. coup ne matche pasbeaucoup, mais enfant matche bien enfants. Mettez verify: "none" pour voirla liste brute.

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

Certaines chansons n'ont pas de paroles. Une page lyrics.com valide peutsimplement 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 à unerequête limitée par un corps vide plutôt que par un code d'erreur normal. Ceserveur le détecte et renvoie une erreur throttled explicite, qui vous ditd'attendre et de réessayer. Il ne présente jamais une limitation comme « aucunrésultat », ce qui serait indiscernable d'une vraie réponse.

Configuration

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

À propos du User-Agent

Le serveur s'identifie honnêtement par défaut, en nommant le projet et en pointantvers 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 simplecurl/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 surchargeexiste pour que vous ne restiez pas bloqué ; ce que vous y mettez relève de votredécision et de votre responsabilité.

Dépannage

Erreurs « throttled ». lyrics.com vous limite. Le serveur réessaie déjà avecbackoff 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 courammentplusieurs minutes, pas quelques secondes : attendez une minute ou plus avant deréessayer, et augmentez LYRICSCOM_MIN_INTERVAL_MS si cela persiste. Une erreurthrottled 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 leserveur n'a pas su lire la réponse. Merci d'ouvrir une issueen indiquant la requête utilisée. Le serveur signale volontairement ce cas au lieude faire comme s'il n'avait rien trouvé.

Résultats vides. Si raw_result_count est supérieur à zéro alors queresults est vide, lyrics.com a bien renvoyé des lignes mais aucune ne contientré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 cellesque vous ouvririez dans un navigateur et les lit aveccheerio. Il récupère une page à la fois, à environ unerequête par seconde, ralentit quand le site le lui demande, et garde un petitcache 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 dumarkup de lyrics.com avec du texte de remplissage, ce qui rend les tests deparsing 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 etest publiée séparément sous mcp-lyricscom/client, utilisable comme simplebibliothè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.comque 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 votreassistant. Il ne parcourt pas le site, ne constitue aucune base de paroles, etn'écrit rien sur le disque. Les pages restent en mémoire quelques minutes pour nepas solliciter le site inutilement.

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

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

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

Licence

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