mcp-lyricscom
[npm]
[CI]
[license]
[MCP Registry]
[Glama]
[M8ven]
[LobeHub]
[Install in Cursor]
[Install in VS Code]
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
[Install in Cursor]
[Install in VS Code]
Claude Code
Claude Desktop, Cursor, and any client using the standard config format
Node 24 or later is required, and no environment variable has to be set.
With Docker
-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.1.0.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.
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
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
[Install in Cursor]
[Install in VS Code]
Claude Code
Claude Desktop, Cursor, et tout client au format de configuration standard
Node 24 ou plus récent est nécessaire, et aucune variable d'environnement n'est à
renseigner.
Avec Docker
-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.1.0.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é.
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
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.
