Lyrics.com

Pesquise letras de músicas no lyrics.com por palavra ou título e obtenha a letra completa. Nenhuma chave de API é necessária.

GitHubExperimente este MCPPatrocinado

Documentação

mcp-lyricscom

lyrics.com é um grande catálogo público de letras de músicas. Ele arquiva uma música pelo seu título, seu artista, o álbum em que apareceu e o ano, e guarda as próprias palavras. Sua busca alcança o interior dessas palavras.

Este servidor conecta um cliente de chat a esse catálogo. Você pode pesquisar uma música por uma linha que você lembra, pesquisar por título e artista, e ler as palavras de uma música, um trecho por vez, com as palavras que você procurava localizadas no texto. Ele não precisa de chave de API nem de conta.

Versão em francês

Instalação

Instalação em um clique

Claude Code

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

Claude Desktop, Cursor e qualquer cliente que use o formato de configuração padrão

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

Node 24 ou posterior é necessário, e nenhuma variável de ambiente precisa ser definida.

Com Docker

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

-i mantém o stdin aberto, que é por onde o protocolo trafega, e -t é omitido porque um TTY reescreve o fluxo. O contêiner precisa de HTTPS de saída para www.lyrics.com, e nada mais: sem volume, sem porta, sem credencial.

Pacote, sem npm

Baixe mcp-lyricscom-2.0.1.mcpb de a versão mais recente e abra-o. Um cliente que suporta pacotes MCP o instala por conta própria, sem npm e sem arquivo de configuração para editar. O pacote carrega suas dependências, então nada é baixado no momento da instalação.

O que você pode perguntar

"Qual música tem 'I've got a hand for you'?"
"Encontre a letra de Wichita Lineman do Glen Campbell."
"Leia a segunda metade dessas palavras."
"Onde a palavra 'lineman' aparece nessa música?"
"Em quais álbuns essa música está?"

O caminho comum vai de uma busca a uma leitura: uma linha carrega um id, e get_lyrics recebe esse id.

Ferramentas

Ferramenta	O que ela faz
`search_lyrics`	Encontra uma música a partir de uma linha dentro de suas palavras.
`search_songs`	Encontra músicas por título, restringido por artista.
`get_lyrics`	Lê as palavras de uma música, um trecho por vez.

`search_lyrics`

Encontra uma música a partir de palavras dentro de sua letra. O site classifica de forma frouxa, então uma correspondência é verificada antes de ser entregue.

Argumento	Tipo	Obrigatório	O que ele faz
`query`	string, 1 a 120 caracteres	sim	A linha, ou parte dela, para procurar.
`limit`	inteiro, 1 a 50, padrão `10`	não	Linhas para entregar.
`page`	inteiro, 1 a 20, padrão `1`	não	Qual página de linhas.
`verify`	`snippet`, `full` ou `none`, padrão `snippet`	não	Como confirmar que as palavras realmente aparecem.
`include_excerpt`	booleano, padrão `true`	não	Carregar a linha correspondente com cada linha.

verify decide o valor de uma linha. snippet verifica o trecho que o site já retornou e não custa nada. full busca até cinco páginas de músicas e verifica as palavras completas, o que é lento e pode provocar limitação de taxa. none entrega o que o site classificou, sem verificação.

Em retorno: linhas carregando id, que get_lyrics recebe; title; artist; album e year, null onde o catálogo não informa nenhum; source_url; e excerpt, a linha correspondente. raw_result_count é o que o site retornou e filtered_out quantas linhas a verificação removeu, então os dois juntos dizem quão frouxa a classificação foi. has_more e next_page continuam.

`search_songs`

Encontra músicas por título, restringido por artista.

Argumento	Tipo	Obrigatório	O que ele faz
`title`	string, 1 a 120 caracteres	sim	O título da música, ou parte dele.
`artist`	string, até 120 caracteres	não	Manter as músicas creditadas a este artista.
`limit`	inteiro, 1 a 50, padrão `10`	não	Linhas para entregar.
`page`	inteiro, 1 a 20, padrão `1`	não	Qual página de linhas.
`match`	`loose` ou `strict`, padrão `loose`	não	Quão próximo o artista precisa corresponder.

Em retorno: as linhas que search_lyrics retorna, com artist_filter ecoando o que foi pedido e filtered_out contando o que a restrição de artista removeu. strict mantém os artistas cujo nome corresponde como escrito; loose aceita um nome escrito de forma diferente.

`get_lyrics`

Lê as palavras de uma música. Letras longas são entregues um trecho por vez.

Argumento	Tipo	Obrigatório	O que ele faz
`id`	string	um de dois	O id da música que uma linha de busca carrega.
`url`	uma URL do lyrics.com	um de dois	O endereço da página da música.
`max_chars`	inteiro, 200 a 20000, padrão `6000`	não	Caracteres de texto para entregar nesta chamada.
`offset`	inteiro, 0 ou mais, padrão `0`	não	Deslocamento de caracteres para retomar.
`highlight`	string, até 120 caracteres	não	Palavras para localizar dentro do texto.

Em retorno: status, lendo ok ou no_lyrics para uma página que o site mantém sem palavras; title, artist e source_url; e lyrics, o trecho em si. A leitura é descrita por total_chars, returned_chars, offset, next_offset e truncated: passe next_offset de volta para continuar lendo, e null ali significa o fim. line_count conta as linhas do trecho, e highlight responde para cada palavra se ela foi found e em qual line_number, que é null quando não foi.

Configuração

Toda variável é opcional. Defina-as no bloco env da configuração do seu cliente.

Variável	Padrão	O que ela faz
`LYRICSCOM_USER_AGENT`	a identidade do projeto	Nomeia seu aplicativo para o site, com um endereço onde uma pessoa pode ser contatada.
`LYRICSCOM_MIN_INTERVAL_MS`	`1100`	Intervalo entre duas solicitações, de 500 a 60000.
`LYRICSCOM_TIMEOUT_MS`	`15000`	Prazo para uma solicitação, de 1000 a 120000.
`LYRICSCOM_MAX_RETRIES`	`3`	Tentativas após uma falha transitória, de 0 a 10.
`LYRICSCOM_CACHE_TTL_MS`	`900000`	Quanto tempo uma resposta permanece na memória, de 0 a 86400000.
`LYRICSCOM_CACHE_MAX_ENTRIES`	`200`	Respostas mantidas na memória de uma vez, de 0 a 10000.
`LYRICSCOM_LOG_LEVEL`	`error`	`silent`, `error`, `info` ou `debug`, escrito em stderr.

Um valor fora do intervalo cai para o padrão, e o motivo é escrito em stderr.

Sobre o User-Agent. Este servidor nomeia o projeto e vincula ao seu repositório, e o site atende a isso. Ele recusa alguns agentes de ferramentas genéricos diretamente: um curl simples recebe um 403. Um erro blocked_user_agent significa que a identidade foi recusada, e LYRICSCOM_USER_AGENT permite que você defina uma de sua escolha. O que você coloca lá é sua decisão e sua responsabilidade.

Erros

Toda falha carrega um destes códigos, uma mensagem e, onde ajuda, uma dica nomeando o próximo passo.

Código	O que aconteceu	O que fazer
`not_found`	O site respondeu e não tem tal música.	Verifique o id com `search_songs`.
`invalid_input`	Os argumentos foram recusados antes de qualquer solicitação sair.	Leia a mensagem, que nomeia o argumento.
`throttled`	O site pediu que este cliente diminuísse o ritmo.	Espere, então chame novamente com os mesmos argumentos. A música ainda está lá.
`blocked_user_agent`	O site recusou a identidade que este cliente enviou.	Defina `LYRICSCOM_USER_AGENT`.
`parse_failure`	A página carregou e o conteúdo esperado estava ausente.	Reporte em o rastreador de problemas.
`network_error`	A solicitação não foi concluída.	Tente novamente em breve.
`timeout`	A solicitação passou do prazo.	Aumente `LYRICSCOM_TIMEOUT_MS`, ou peça um `max_chars` menor.

throttled e blocked_user_agent são os dois nomes deste servidor para uma recusa de atendimento, e um chamador que lê várias fontes os normaliza para o que chama de limitação de taxa.

Como biblioteca

A camada que lê o site é publicada separadamente, com seu ritmo, seu cache e seus erros, e sem protocolo anexado.

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 e getSong cada um responde { data, cached }, e lançam um erro carregando um dos códigos acima. O intervalo mínimo entre duas solicitações também vale aqui.

Ritmo e atribuição

As solicitações saem uma de cada vez com pelo menos um segundo entre elas, e o mínimo de meio segundo vale independentemente de como o servidor está configurado. Uma busca verify: "full" busca até cinco páginas de músicas, que é a coisa mais cara que este servidor faz.

Todo resultado carrega o artista, o título e o endereço da página da música. As letras de músicas são o trabalho de seus autores e editoras. Este projeto não reivindica direitos sobre elas, não envia nenhum banco de dados delas e não grava nada em disco.

Este servidor MCP é um projeto não oficial, sem afiliação com lyrics.com.

Privacidade

Este servidor não coleta nada sobre você e não envia nada ao seu autor. Ele roda na sua máquina, contata www.lyrics.com e nada mais, mantém suas respostas na memória enquanto roda e não grava nada em disco. PRIVACY.md declara o que uma requisição carrega e quais configurações alteram qualquer parte disso.

Desenvolvimento

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

Os testes rodam contra fixtures geradas e não fazem nenhuma requisição de rede. A suíte ao vivo, npm run test:live, faz uma requisição por rota e roda todas as noites contra o próprio site.

Contribuindo

Bugs, perguntas e ideias pertencem ao rastreador de issues. Pull requests são bem-vindos; abrir uma issue primeiro ajuda a concordar sobre o formato da mudança. Veja CONTRIBUTING.md.

Licença

MIT, veja LICENSE. As letras pertencem aos seus autores e editoras.

mcp-lyricscom (français)

Versão em inglês

lyrics.com é um grande catálogo público de letras de músicas. Ele classifica uma música pelo seu título, artista, álbum em que apareceu e ano, e contém as próprias letras. Sua busca vai para dentro dessas letras.

Este servidor conecta um cliente de conversa a esse catálogo. Pode-se buscar uma música por um verso que você lembra, buscar por título e artista, e ler as letras de uma música em partes, com as palavras buscadas localizadas no texto. Nenhuma chave de API, nenhuma conta.

Instalação

Instalação em um clique

Claude Code

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

Claude Desktop, Cursor, e qualquer cliente no formato de configuração padrão

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

Node 24 ou mais recente é necessário, e nenhuma variável de ambiente precisa ser preenchida.

Com Docker

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

-i mantém a entrada padrão aberta, que é o canal do protocolo, e -t é omitido porque um TTY reescreve o fluxo. O contêiner precisa de acesso HTTPS de saída para www.lyrics.com, e nada mais: nenhum volume, nenhuma porta, nenhum identificador.

Bundle, sem npm

Baixe mcp-lyricscom-2.0.1.mcpb de a última publicação e abra-o. Um cliente que gerencia bundles MCP o instala sozinho, sem npm e sem arquivo de configuração para modificar. O bundle carrega suas dependências, então nada é baixado na instalação.

O que se pode pedir

« Qual é a música que diz "I've got a hand for you" ? »
« Encontre as letras de Wichita Lineman por Glen Campbell. »
« Leia a segunda metade dessas letras. »
« Onde aparece a palavra "lineman" nessa música ? »
« Em quais álbuns essa música aparece ? »

O caminho comum vai de uma busca a uma leitura: uma linha carrega um id, e get_lyrics retoma esse identificador.

As ferramentas

Ferramenta	O que ela faz
`search_lyrics`	Encontra uma música a partir de um verso das suas letras.
`search_songs`	Encontra músicas por título, restringidas por artista.
`get_lyrics`	Lê as letras de uma música, em partes.

`search_lyrics`

Encontra uma música a partir de palavras contidas nas suas letras. O site classifica amplamente, então uma correspondência é verificada antes de ser servida.

Argumento	Tipo	Obrigatório	O que ele faz
`query`	string, 1 a 120 caracteres	sim	O verso, ou uma parte, a buscar.
`limit`	inteiro, 1 a 50, padrão `10`	não	Linhas a servir.
`page`	inteiro, 1 a 20, padrão `1`	não	Qual página de linhas.
`verify`	`snippet`, `full` ou `none`, padrão `snippet`	não	Como confirmar que as palavras estão lá.
`include_excerpt`	booleano, padrão `true`	não	Carregar o verso correspondente em cada linha.

verify decide o que vale uma linha. snippet verifica o trecho que o site já renderizou e não custa nada. full vai buscar até cinco páginas de músicas e verifica as letras inteiras, o que é lento e pode acionar uma limitação. none serve o que o site classificou, sem verificação.

Em retorno: linhas carregando id, que get_lyrics retoma; title; artist; album e year, null onde o catálogo não indica nada; source_url; e excerpt, o verso correspondente. raw_result_count é o que o site renderizou e filtered_out o número de linhas que a verificação removeu, então os dois juntos dizem quão ampla era a classificação. has_more e next_page continuam.

`search_songs`

Encontra músicas por título, restringidas por artista.

Argumento	Tipo	Obrigatório	O que ele faz
`title`	string, 1 a 120 caracteres	sim	O título da música, ou uma parte.
`artist`	string, até 120 caracteres	não	Manter apenas as músicas desse artista.
`limit`	inteiro, 1 a 50, padrão `10`	não	Linhas a servir.
`page`	inteiro, 1 a 20, padrão `1`	não	Qual página de linhas.
`match`	`loose` ou `strict`, padrão `loose`	não	O rigor da correspondência no artista.

Em retorno: as linhas que search_lyrics renderiza, com artist_filter que devolve o que foi pedido e filtered_out que conta o que a restrição no artista removeu. strict mantém os artistas cujo nome corresponde como escrito; loose aceita um nome escrito de outra forma.

`get_lyrics`

Lê as letras de uma música. Letras longas são servidas em partes.

Argumento	Tipo	Obrigatório	O que ele faz
`id`	string	um dos dois	O identificador que uma linha carrega.
`url`	um endereço lyrics.com	um dos dois	O endereço da página da música.
`max_chars`	inteiro, 200 a 20000, padrão `6000`	não	Caracteres de texto a servir nesta chamada.
`offset`	inteiro, 0 ou mais, padrão `0`	não	Posição em caracteres onde retomar.
`highlight`	string, até 120 caracteres	não	Palavras a localizar no texto.

Em retorno: status, valendo ok ou no_lyrics para uma página que o site contém sem letras; title, artist e source_url; e lyrics, a parte em si. A leitura é descrita por total_chars, returned_chars, offset, next_offset e truncated: devolva next_offset para continuar, e null marca o fim. line_count conta as linhas da parte, e highlight responde para cada palavra se ela foi found e em qual line_number, null quando não foi.

Configuração

Cada variável é opcional. Elas são colocadas no bloco env da configuração do cliente.

Variável	Padrão	O que ela faz
`LYRICSCOM_USER_AGENT`	a identidade do projeto	Nomeia sua aplicação junto ao site, com um endereço para contatar uma pessoa.
`LYRICSCOM_MIN_INTERVAL_MS`	`1100`	Intervalo entre duas requisições, de 500 a 60000.
`LYRICSCOM_TIMEOUT_MS`	`15000`	Tempo limite de uma requisição, de 1000 a 120000.
`LYRICSCOM_MAX_RETRIES`	`3`	Tentativas após uma falha temporária, de 0 a 10.
`LYRICSCOM_CACHE_TTL_MS`	`900000`	Duração durante a qual uma resposta fica na memória, de 0 a 86400000.
`LYRICSCOM_CACHE_MAX_ENTRIES`	`200`	Respostas mantidas na memória por vez, de 0 a 10000.
`LYRICSCOM_LOG_LEVEL`	`error`	`silent`, `error`, `info` ou `debug`, escrito na saída de erro.

Um valor fora do seu intervalo cai no padrão, e o motivo é escrito na saída de erro.

Sobre o User-Agent. Este servidor nomeia o projeto e aponta para o seu repositório, e o site o atende. Ele recusa, no entanto, certos agentes de ferramentas genéricas: um curl nu recebe um 403. Um erro blocked_user_agent significa que a identidade enviada foi recusada, e LYRICSCOM_USER_AGENT permite definir uma de sua escolha. O que você coloca nela é sua decisão e sua responsabilidade.

Erros

Cada falha carrega um desses códigos, uma mensagem, e quando ajuda uma indicação do próximo passo.

Código	O que aconteceu	O que fazer
`not_found`	O site respondeu, e não tem essa música.	Verifique o identificador com `search_songs`.
`invalid_input`	Os argumentos foram recusados antes de qualquer requisição.	Leia a mensagem, que nomeia o argumento.
`throttled`	O site pede que este cliente desacelere.	Espere, então chame novamente com os mesmos argumentos. A música ainda está lá.
`blocked_user_agent`	O site recusou a identidade enviada por este cliente.	Defina `LYRICSCOM_USER_AGENT`.
`parse_failure`	A página carregou e o conteúdo esperado está ausente.	Reporte em o rastreador de incidentes.
`network_error`	A requisição não foi concluída.	Tente novamente em breve.
`timeout`	A requisição excedeu seu tempo limite.	Aumente `LYRICSCOM_TIMEOUT_MS`, ou peça um `max_chars` menor.
`throttled` e `blocked_user_agent` são os dois nomes que este servidor dá a uma
recusa de servir, e um chamador que lê várias fontes os associa ao que
chama de limitação de taxa.

Como biblioteca

A camada que lê o site é publicada isoladamente, com seu ritmo, seu cache e seus erros, sem protocolo anexado.

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 e getSong respondem cada um { data, cached }, e lançam um erro com um dos códigos acima. O intervalo mínimo entre duas requisições também se aplica aqui.

Ritmo e atribuição

As requisições saem uma a uma com pelo menos um segundo entre elas, e o intervalo mínimo de meio segundo se mantém independentemente da configuração. Uma busca em verify: "full" procura até cinco páginas de músicas, o que é a coisa mais custosa que este servidor faz.

Cada resultado traz o artista, o título e o endereço da página da música. As letras são obra de seus autores e de seus editores. Este projeto não reivindica nenhum direito sobre elas, não embute nenhuma base de letras e não escreve nada no disco.

Este MCP é um projeto não oficial, sem afiliação com lyrics.com.

Privacidade

Este servidor não coleta nada sobre você e não envia nada ao seu autor. Ele roda na sua máquina, anexa apenas www.lyrics.com, mantém suas respostas em memória enquanto roda, e não escreve nada no disco. PRIVACY.md diz o que uma requisição carrega e quais configurações mudam isso.

Desenvolvimento

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

Os testes são executados em fixtures geradas e não emitem nenhuma requisição. A suíte ao vivo, npm run test:live, emite uma requisição por rota e roda todas as noites contra o próprio site.

Contribuindo

Anomalias, perguntas e ideias têm seu lugar em o rastreador de problemas. Propostas de modificação são bem-vindas; abrir um ticket primeiro ajuda a alinhar sobre a forma da mudança. Veja CONTRIBUTING.md.

Licença

MIT, veja LICENSE. As letras pertencem aos seus autores e aos seus editores.