LRCLIB

Pesquise faixas no LRCLIB e obtenha letras simples ou sincronizadas por tempo (LRC). Sem chave de API.

Documentação

mcp-lrclib

LRCLIB é um banco de dados aberto e gratuito de letras de músicas, construído pelas pessoas que o utilizam e oferecido a qualquer pessoa sem chave ou conta. Ele contém duas formas das palavras: o texto simples de uma música e a forma LRC, onde cada linha carrega o momento em que é cantada, que é o que uma exibição de karaokê ou um painel de letras acompanha. Uma faixa é arquivada lá por seu título, artista, álbum e duração, para que as várias versões de uma música fiquem lado a lado.

Este servidor conecta um cliente de chat a esse banco de dados. Você pode pesquisar uma faixa por título, artista ou álbum, ler as palavras simples de uma música, ler suas linhas sincronizadas com seus timestamps e verificar os metadados de uma versão antes de lê-la. Não requer chave de API nem conta.

Versão em francês

Instalação

Instalação com um clique

Claude Code

claude mcp add lrclib -- npx -y mcp-lrclib

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

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

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

Com Docker

{
  "mcpServers": {
    "lrclib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lrclib: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 lrclib.net, e nada mais: sem volume, sem porta, sem credencial.

Pacote, sem npm

Baixe mcp-lrclib-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 pedir

"Encontre a letra de Le Sud do Nino Ferrer."
"Me dê a letra sincronizada de Bohemian Rhapsody para eu acompanhar."
"Qual versão de Hallelujah está no LRCLIB, e quanto tempo dura cada uma?"
"Leia a segunda metade dessa letra."
"A faixa 3396226 tem letra sincronizada?"

O caminho comum vai de uma pesquisa a uma leitura: search_tracks nomeia um id, e get_lyrics recebe esse id.

Ferramentas

Ferramenta	O que faz
`search_tracks`	Encontra faixas por título, artista ou álbum, com seus metadados.
`get_lyrics`	Lê as palavras de uma faixa, simples ou com seus timestamps.
`get_track`	Lê os metadados de uma faixa pelo seu id, sem as palavras.

O LRCLIB arquiva uma faixa pelos seus metadados, então uma pesquisa alcança uma música pelo seu título, artista ou álbum. Uma palavra lembrada de dentro de uma música não encontra nada lá.

`search_tracks`

Encontra as faixas cujos metadados correspondem, em uma pesquisa de texto livre ou em campos próprios. Várias versões de uma música voltam lado a lado, e seu álbum e duração as distinguem.

Argumento	Tipo	Obrigatório	O que faz
`query`	string, 1 a 200 caracteres	não	Pesquisa de texto livre, como em `nino ferrer le sud`.
`track_name`	string, até 200 caracteres	não	Título da música, para pesquisa por campo.
`artist_name`	string, até 200 caracteres	não	Nome do artista, para pesquisa por campo.
`album_name`	string, até 200 caracteres	não	Nome do álbum, para restringir uma pesquisa por campo.
`limit`	inteiro, 1 a 50, padrão `10`	não	Linhas a servir. O LRCLIB responde até 20 por pesquisa.

Passe query, ou um dos três campos.

Em retorno: linhas carregando id, que get_lyrics e get_track recebem; track_name e artist_name; album_name e duration_seconds, que distinguem duas versões de uma música; instrumental; has_plain_lyrics e has_synced_lyrics, para que linhas sincronizadas possam ser verificadas antes de serem solicitadas; e source_url. Junto vêm result_count e total_available, as faixas que o LRCLIB serviu antes de limit ser aplicado. album_name e duration_seconds são null em uma faixa arquivada sem eles, e as linhas não carregam palavras: get_lyrics lê essas.

`get_lyrics`

Lê as palavras de uma faixa, seja como texto simples ou como linhas LRC carregando o momento em que cada uma é cantada. Letras longas são servidas em partes, retomando em um limite de linha.

Argumento	Tipo	Obrigatório	O que faz
`id`	inteiro, positivo	não	O id da faixa no LRCLIB, como `search_tracks` o retornou.
`artist_name`	string, até 200 caracteres	não	Nome do artista, correspondência exata. Necessário quando `id` está ausente.
`track_name`	string, até 200 caracteres	não	Título da música, correspondência exata. Necessário quando `id` está ausente.
`album_name`	string, até 200 caracteres	não	Nome do álbum, para escolher entre versões.
`duration_seconds`	número, positivo	não	Duração da faixa, para escolher entre versões de comprimento diferente.
`format`	`plain`, `synced` ou `both`, padrão `plain`	não	Qual forma das palavras servir.
`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	Deslocamento de caracteres para retomar.

Em retorno: status, que lê ok, instrumental para uma faixa sem palavras para cantar, ou no_lyrics para uma arquivada sem elas; track com seu id, título, artista, álbum, duração e source_url; plain_lyrics; synced_lyrics como texto LRC bruto e synced_lines como uma lista de { time_seconds, text }, com synced_lines_truncated quando a parte os cortou. A leitura é descrita por paginated_form, total_chars, returned_chars, offset, next_offset e truncated: passe next_offset de volta para continuar lendo, e null lá significa o fim. attribution é a linha a citar quando as palavras são mostradas. Um status de instrumental é uma resposta completa.

`get_track`

Lê os metadados de uma faixa pelo seu id, deixando as palavras de lado. Ele confirma uma versão antes que as palavras sejam solicitadas e resolve um id trazido de antes em uma conversa.

Argumento	Tipo	Obrigatório	O que faz
`id`	inteiro, positivo	sim	O id da faixa no LRCLIB, como `search_tracks` o retornou.

Em retorno: track, contendo os campos que uma linha de pesquisa carrega, e duration_formatted como m:ss, que é null quando a faixa é arquivada sem duração. has_plain_lyrics e has_synced_lyrics dizem quais formas get_lyrics pode servir para ela.

Configuração

Todas as variáveis são opcionais. Defina-as no bloco env da configuração do seu cliente.

Variável	Padrão	O que faz
`LRCLIB_USER_AGENT`	a identidade do projeto	Nomeia seu aplicativo para o LRCLIB, com um endereço onde uma pessoa pode ser contatada.
`LRCLIB_MIN_INTERVAL_MS`	`500`	Intervalo entre duas solicitações, de 200 a 60000. Um valor abaixo do mínimo é recusado e este é usado.
`LRCLIB_TIMEOUT_MS`	`15000`	Prazo para uma solicitação, de 1000 a 120000.
`LRCLIB_MAX_RETRIES`	`3`	Tentativas após uma falha transitória, de 0 a 10.
`LRCLIB_CACHE_TTL_MS`	`900000`	Quanto tempo uma resposta permanece na memória, de 0 a 86400000.
`LRCLIB_CACHE_MAX_ENTRIES`	`200`	Respostas mantidas na memória de uma vez, de 0 a 10000.
`LRCLIB_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.

Erros

Toda falha carrega um de seis 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 LRCLIB respondeu, e não contém tal faixa.	Verifique a grafia com `search_tracks`.
`invalid_input`	Os argumentos foram recusados antes de qualquer solicitação sair.	Leia a mensagem, que nomeia o argumento.
`rate_limited`	O LRCLIB pediu que este cliente diminuísse o ritmo.	Aguarde o número de segundos que a dica nomeia e chame novamente com os mesmos argumentos. A faixa ainda está lá.
`upstream_error`	O LRCLIB respondeu em um formato que este cliente não consegue ler.	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 `LRCLIB_TIMEOUT_MS`, ou peça um `max_chars` menor.

Como biblioteca

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

import { LrclibClient } from "mcp-lrclib/client";

const client = new LrclibClient();
const { data, cached } = await client.getById(3396226);
console.log(data.track_name, data.synced_lyrics !== null, cached);

search, get e getById cada um responde { data, cached }, e lançam um erro carregando um dos seis códigos. O intervalo mínimo entre duas solicitações também vale aqui.

Ritmo e atribuição

As solicitações são enviadas uma de cada vez, com um intervalo mínimo entre elas, e esse limite se mantém independentemente de como o servidor está configurado. O User-Agent sempre termina com a identidade do projeto e um endereço onde uma pessoa pode ser contatada. LRCLIB é um serviço gratuito e publica sua API para máquinas lerem, e este servidor a lê sob demanda, uma chamada por vez, em resposta a algo que você pediu.

Cada resultado traz o artista, o título e o endereço da página LRCLIB correspondente, e o get_lyrics carrega o attribution, os três escritos em uma única linha.

As letras de músicas são obras de seus autores e editoras. Este projeto não reivindica direitos sobre elas, não armazena nenhum banco de dados delas, não grava nada em disco e não contribui de volta para o LRCLIB. Este servidor MCP é um projeto não oficial, sem afiliação com o LRCLIB.

Privacidade

Este servidor não coleta nada sobre você e não envia nada ao seu autor. Ele roda na sua máquina, contata o lrclib.net e nada mais, mantém as respostas na memória enquanto está em execução e não grava nada em disco. PRIVACY.md declara o que uma solicitaçã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 gerados e não fazem nenhuma solicitação de rede. A suíte ao vivo, npm run test:live, faz uma solicitação por rota e roda todas as noites contra o próprio serviço.

Contribuindo

Bugs, perguntas e ideias pertencem ao rastreador de problemas. Pull requests são bem-vindos; abrir um problema primeiro ajuda a concordar sobre a forma da mudança. Veja CONTRIBUTING.md.

Licença

MIT, veja LICENSE. As letras pertencem aos seus autores e editoras, e o banco de dados ao LRCLIB e seus contribuidores.

mcp-lrclib (français)

Versão em inglês

LRCLIB é um banco de letras de músicas livre e aberto, alimentado por aqueles que o usam e oferecido a todos sem chave nem conta. Ele contém duas formas de letras: o texto simples de uma música, e a forma LRC, onde cada linha carrega o momento em que é cantada, o que um display de karaokê ou um painel de letras segue. Um título é classificado por seu nome, seu artista, seu álbum e sua duração, de modo que as diferentes versões de uma mesma música ficam lado a lado.

Este servidor conecta um cliente de conversa a esse banco. Pode-se buscar um título por seu nome, seu artista ou seu álbum, ler as letras simples de uma música, ler suas linhas com carimbo de tempo com suas marcas de tempo, e verificar a ficha de uma versão antes de lê-la. Nenhuma chave de API, nenhuma conta.

Instalação

Instalação em um clique

Claude Code

claude mcp add lrclib -- npx -y mcp-lrclib

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

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

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

Com Docker

{
  "mcpServers": {
    "lrclib": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-lrclib: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 lrclib.net, e nada mais: nenhum volume, nenhuma porta, nenhuma credencial.

Bundle, sem npm

Baixe o mcp-lrclib-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

« Encontre-me as letras de Le Sud do Nino Ferrer. »
« Dê-me as letras com carimbo de tempo de Bohemian Rhapsody para eu seguir. »
« Quais versões de Hallelujah existem no LRCLIB, e qual é a duração delas? »
« Leia-me a segunda metade dessas letras. »
« O título 3396226 tem letras sincronizadas? »

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

As ferramentas

Ferramenta	O que ela faz
`search_tracks`	Encontra títulos por nome, artista ou álbum, com suas fichas.
`get_lyrics`	Lê as letras de um título, simples ou com carimbo de tempo.
`get_track`	Lê a ficha de um título por seu identificador, sem as letras.

LRCLIB classifica um título por sua ficha, então uma busca alcança uma música por seu nome, seu artista ou seu álbum. Uma palavra retida de dentro de uma música não encontra nada.

`search_tracks`

Encontra os títulos cuja ficha corresponde, em uma busca livre ou por campos. Várias versões de uma mesma música voltam lado a lado, e seu álbum e sua duração as distinguem.

Argumento	Tipo	Obrigatório	O que ele faz
`query`	string, 1 a 200 caracteres	não	Busca livre, por exemplo `nino ferrer le sud`.
`track_name`	string, até 200 caracteres	não	Nome da música, para uma busca por campos.
`artist_name`	string, até 200 caracteres	não	Nome do artista, para uma busca por campos.
`album_name`	string, até 200 caracteres	não	Nome do álbum, para restringir uma busca por campos.
`limit`	inteiro, 1 a 50, padrão `10`	não	Linhas a servir. LRCLIB retorna até 20 por busca.

Passe query, ou um dos três campos.

Em retorno: linhas que carregam id, que get_lyrics e get_track retomam; track_name e artist_name; album_name e duration_seconds, que distinguem duas versões de uma mesma música; instrumental; has_plain_lyrics e has_synced_lyrics, que permitem verificar a existência das linhas com carimbo de tempo antes de pedi-las; e source_url. Vêm também result_count e total_available, os títulos que LRCLIB serviu antes da aplicação de limit. album_name e duration_seconds valem null em um título classificado sem eles, e as linhas não carregam nenhuma letra: get_lyrics as lê.

`get_lyrics`

Lê as letras de um título, em texto simples ou em linhas LRC que carregam o momento em que cada uma é cantada. Letras longas são servidas em partes, cortadas em uma quebra de linha.

Argumento	Tipo	Obrigatório	O que ele faz
`id`	inteiro, positivo	não	O identificador LRCLIB retornado por `search_tracks`.
`artist_name`	string, até 200 caracteres	não	Nome do artista, correspondência exata. Necessário sem `id`.
`track_name`	string, até 200 caracteres	não	Nome da música, correspondência exata. Necessário sem `id`.
`album_name`	string, até 200 caracteres	não	Nome do álbum, para escolher entre versões.
`duration_seconds`	número, positivo	não	Duração do título, para escolher entre versões de durações diferentes.
`format`	`plain`, `synced` ou `both`, padrão `plain`	não	A forma das letras a servir.
`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.

Em retorno: status, que vale ok, instrumental para um título sem letras para cantar, ou no_lyrics para um título classificado sem elas; track com seu identificador, seu nome, seu artista, seu álbum, sua duração e seu source_url; plain_lyrics; synced_lyrics em texto LRC bruto e synced_lines em lista de { time_seconds, text }, com synced_lines_truncated quando a parte as cortou. A leitura é descrita por paginated_form, total_chars, returned_chars, offset, next_offset e truncated: devolva next_offset para continuar, e null marca o fim. attribution é a linha a citar quando as letras são mostradas. Um status a instrumental é uma resposta completa.

`get_track`

Lê a ficha de um título desde seu identificador, sem as letras. Ela confirma uma versão antes que se peçam as letras, e resolve um identificador vindo de uma troca anterior.

Argumento	Tipo	Obrigatório	O que ele faz
`id`	inteiro, positivo	sim	O identificador LRCLIB retornado por `search_tracks`.

Em retorno: track, que carrega os campos de uma linha de busca, e duration_formatted na forma m:ss, null para um título classificado sem duração. has_plain_lyrics e has_synced_lyrics dizem quais formas get_lyrics pode servir.

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
`LRCLIB_USER_AGENT`	a identidade do projeto	Nomeia sua aplicação junto ao LRCLIB, com um endereço onde uma pessoa pode ser contatada.
`LRCLIB_MIN_INTERVAL_MS`	`500`	Intervalo entre duas solicitações, de 200 a 60000. Um valor abaixo do mínimo é recusado em favor deste.
`LRCLIB_TIMEOUT_MS`	`15000`	Tempo limite de uma solicitação, de 1000 a 120000.
`LRCLIB_MAX_RETRIES`	`3`	Tentativas após uma falha temporária, de 0 a 10.
`LRCLIB_CACHE_TTL_MS`	`900000`	Duração durante a qual uma resposta permanece na memória, de 0 a 86400000.
`LRCLIB_CACHE_MAX_ENTRIES`	`200`	Respostas mantidas na memória de uma vez, de 0 a 10000.
`LRCLIB_LOG_LEVEL`	`error`	`silent`, `error`, `info` ou `debug`, escrito na saída de erro.

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

Erros

Cada falha carrega um dos seis 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 LRCLIB respondeu e não contém esse título.	Verifique a ortografia com `search_tracks`.
`invalid_input`	Os argumentos foram recusados antes de qualquer requisição.	Leia a mensagem, que nomeia o argumento.
`rate_limited`	O LRCLIB pede que este cliente desacelere.	Aguarde os segundos indicados e chame novamente com os mesmos argumentos. O título ainda está lá.
`upstream_error`	O LRCLIB respondeu em um formato que este cliente não lê.	Reporte em o rastreador de problemas.
`network_error`	A requisição não foi concluída.	Tente novamente em breve.
`timeout`	A requisição excedeu o tempo limite.	Aumente `LRCLIB_TIMEOUT_MS`, ou solicite um `max_chars` menor.

Como biblioteca

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

import { LrclibClient } from "mcp-lrclib/client";

const client = new LrclibClient();
const { data, cached } = await client.getById(3396226);
console.log(data.track_name, data.synced_lyrics !== null, cached);

search, get e getById respondem cada um { data, cached }, e lançam um erro com um dos seis códigos. 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 um intervalo mínimo entre elas, e esse piso vale independentemente da configuração. O User-Agent sempre termina com a identidade do projeto e um endereço para contatar uma pessoa. O LRCLIB é um serviço gratuito e publica sua API para ser lida por máquinas, e este servidor a lê sob demanda, uma chamada por vez, em resposta ao que você solicitou.

Cada resultado traz o artista, o título e o endereço da página LRCLIB, e get_lyrics traz attribution, esses três elementos escritos em uma linha.

As letras são obras de seus autores e editores. Este projeto não reivindica nenhum direito sobre elas, não inclui nenhuma base de letras, não grava nada no disco e não contribui com nada para o LRCLIB. Este MCP é um projeto não oficial, sem afiliação ao LRCLIB.

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 lrclib.net, mantém suas respostas em memória enquanto roda, e não grava 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 serviço.

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 a forma da mudança. Veja CONTRIBUTING.md.

Licença

MIT, veja LICENSE. As letras pertencem aos seus autores e editores, e a base ao LRCLIB e seus contribuidores.