LRCLIB

Busca pistas en LRCLIB y obtén letras en texto plano o sincronizadas (LRC). No requiere clave API.

Documentación

mcp-lrclib

LRCLIB es una base de datos abierta y gratuita de letras de canciones, construida por las personas que la usan y ofrecida a cualquiera sin clave ni cuenta. Contiene dos formas de las palabras: el texto plano de una canción y la forma LRC, donde cada línea lleva el momento en que se canta, que es lo que sigue una pantalla de karaoke o un panel de letras. Una pista se archiva allí por su título, su artista, su álbum y su duración, de modo que las varias versiones de una canción se muestran una al lado de la otra.

Este servidor conecta un cliente de chat a esa base de datos. Puedes buscar una pista por título, artista o álbum, leer las palabras planas de una canción, leer sus líneas sincronizadas con sus marcas de tiempo y consultar los metadatos de una versión antes de leerla. No necesita clave de API ni cuenta.

Versión francesa

Instalación

Instalación en un clic

Claude Code

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

Claude Desktop, Cursor y cualquier cliente que use el formato de configuración estándar

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

Se requiere Node 24 o posterior, y no es necesario establecer ninguna variable de entorno.

Con Docker

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

-i mantiene abierto stdin, que es por donde viaja el protocolo, y -t se omite porque una TTY reescribe el flujo. El contenedor necesita HTTPS saliente hacia lrclib.net, y nada más: sin volumen, sin puerto, sin credencial.

Paquete, sin npm

Descarga mcp-lrclib-2.0.1.mcpb desde la última versión y ábrelo. Un cliente que admita paquetes MCP lo instala por sí solo, sin npm y sin archivo de configuración que editar. El paquete incluye sus dependencias, por lo que no se descarga nada en el momento de la instalación.

Lo que puedes pedir

"Encuéntrame la letra de Le Sud de Nino Ferrer."
"Dame la letra sincronizada de Bohemian Rhapsody para poder seguirla."
"¿Qué versión de Hallelujah hay en LRCLIB y cuánto dura cada una?"
"Léeme la segunda mitad de esa letra."
"¿La pista 3396226 tiene letra sincronizada?"

El camino habitual va de una búsqueda a una lectura: search_tracks nombra un id, y get_lyrics toma ese id.

Herramientas

Herramienta	Qué hace
`search_tracks`	Encuentra pistas por título, artista o álbum, con sus metadatos.
`get_lyrics`	Lee las palabras de una pista, planas o con sus marcas de tiempo.
`get_track`	Lee los metadatos de una pista por su id, sin las palabras.

LRCLIB archiva una pista por sus metadatos, por lo que una búsqueda llega a una canción a través de su título, su artista o su álbum. Una palabra recordada de dentro de una canción no encuentra nada allí.

`search_tracks`

Encuentra las pistas cuyos metadatos coinciden, en una búsqueda de texto libre o en campos propios. Varias versiones de una canción vuelven una al lado de la otra, y su álbum y duración las distinguen.

Argumento	Tipo	Obligatorio	Qué hace
`query`	cadena, de 1 a 200 caracteres	no	Búsqueda de texto libre, como en `nino ferrer le sud`.
`track_name`	cadena, hasta 200 caracteres	no	Título de la canción, para una búsqueda por campo.
`artist_name`	cadena, hasta 200 caracteres	no	Nombre del artista, para una búsqueda por campo.
`album_name`	cadena, hasta 200 caracteres	no	Nombre del álbum, para acotar una búsqueda por campo.
`limit`	entero, de 1 a 50, por defecto `10`	no	Filas a servir. LRCLIB responde hasta 20 por búsqueda.

Pasa query, o uno de los tres campos.

A cambio: filas que llevan id, que get_lyrics y get_track toman; track_name y artist_name; album_name y duration_seconds, que distinguen dos versiones de una canción; instrumental; has_plain_lyrics y has_synced_lyrics, para que las líneas sincronizadas puedan comprobarse antes de pedirlas; y source_url. Junto a ellas vienen result_count y total_available, las pistas que LRCLIB sirvió antes de aplicar limit. album_name y duration_seconds son null en una pista archivada sin ellos, y las filas no llevan palabras en absoluto: get_lyrics las lee.

`get_lyrics`

Lee las palabras de una pista, ya sea como texto plano o como líneas LRC que llevan el momento en que se canta cada una. Las letras largas se sirven en partes, reanudando en un límite de línea.

Argumento	Tipo	Obligatorio	Qué hace
`id`	entero, positivo	no	El id de pista de LRCLIB, como lo devolvió `search_tracks`.
`artist_name`	cadena, hasta 200 caracteres	no	Nombre del artista, con coincidencia exacta. Necesario cuando `id` está ausente.
`track_name`	cadena, hasta 200 caracteres	no	Título de la canción, con coincidencia exacta. Necesario cuando `id` está ausente.
`album_name`	cadena, hasta 200 caracteres	no	Nombre del álbum, para elegir entre versiones.
`duration_seconds`	número, positivo	no	Duración de la pista, para elegir entre versiones de distinta longitud.
`format`	`plain`, `synced` o `both`, por defecto `plain`	no	Qué forma de las palabras servir.
`max_chars`	entero, de 200 a 20000, por defecto `6000`	no	Caracteres de texto a servir en esta llamada.
`offset`	entero, 0 o más, por defecto `0`	no	Desplazamiento de caracteres para reanudar.

A cambio: status, que lee ok, instrumental para una pista sin palabras que cantar, o no_lyrics para una archivada sin ellas; track con su id, título, artista, álbum, duración y source_url; plain_lyrics; synced_lyrics como texto LRC crudo y synced_lines como lista de { time_seconds, text }, con synced_lines_truncated cuando la parte los cortó. La lectura se describe mediante paginated_form, total_chars, returned_chars, offset, next_offset y truncated: pasa next_offset para seguir leyendo, y null allí significa el final. attribution es la línea a citar cuando se muestran las palabras. Un status de instrumental es una respuesta completa.

`get_track`

Lee los metadatos de una pista desde su id, dejando las palabras aparte. Confirma una versión antes de pedir las palabras y resuelve un id traído de antes en una conversación.

Argumento	Tipo	Obligatorio	Qué hace
`id`	entero, positivo	sí	El id de pista de LRCLIB, como lo devolvió `search_tracks`.

A cambio: track, que contiene los campos que lleva una fila de búsqueda, y duration_formatted como m:ss, que es null cuando la pista está archivada sin duración. has_plain_lyrics y has_synced_lyrics indican qué formas get_lyrics puede servir para ella.

Configuración

Toda variable es opcional. Establécelas en el bloque env de la configuración de tu cliente.

Variable	Por defecto	Qué hace
`LRCLIB_USER_AGENT`	la identidad del proyecto	Nombra tu aplicación ante LRCLIB, con una dirección donde se pueda contactar a una persona.
`LRCLIB_MIN_INTERVAL_MS`	`500`	Intervalo entre dos solicitudes, de 200 a 60000. Una cifra por debajo del mínimo se rechaza y se usa esta.
`LRCLIB_TIMEOUT_MS`	`15000`	Plazo para una solicitud, de 1000 a 120000.
`LRCLIB_MAX_RETRIES`	`3`	Intentos tras un fallo transitorio, de 0 a 10.
`LRCLIB_CACHE_TTL_MS`	`900000`	Cuánto tiempo permanece una respuesta en memoria, de 0 a 86400000.
`LRCLIB_CACHE_MAX_ENTRIES`	`200`	Respuestas retenidas en memoria a la vez, de 0 a 10000.
`LRCLIB_LOG_LEVEL`	`error`	`silent`, `error`, `info` o `debug`, escritos en stderr.

Un valor fuera de su rango vuelve al valor por defecto, y la razón se escribe en stderr.

Errores

Cada fallo lleva uno de seis códigos, un mensaje y, donde ayuda, una pista que nombra el siguiente paso.

Código	Qué pasó	Qué hacer
`not_found`	LRCLIB respondió y no tiene tal pista.	Comprueba la ortografía con `search_tracks`.
`invalid_input`	Los argumentos se rechazaron antes de enviar ninguna solicitud.	Lee el mensaje, que nombra el argumento.
`rate_limited`	LRCLIB pidió a este cliente que se ralentizara.	Espera los segundos que nombre la pista y vuelve a llamar con los mismos argumentos. La pista sigue allí.
`upstream_error`	LRCLIB respondió en una forma que este cliente no puede leer.	Repórtalo en el rastreador de incidencias.
`network_error`	La solicitud no se completó.	Inténtalo de nuevo en breve.
`timeout`	La solicitud superó su plazo.	Sube `LRCLIB_TIMEOUT_MS`, o pide un `max_chars` más pequeño.

Como biblioteca

La capa que lee LRCLIB se publica por separado, con su ritmo, su caché y sus errores, y sin protocolo adjunto.

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 y getById responden cada una { data, cached }, y lanzan un error que lleva uno de los seis códigos. El intervalo mínimo entre dos solicitudes también se aplica aquí.

Ritmo y atribución

Las solicitudes se envían de una en una con un intervalo mínimo entre ellas, y ese límite se mantiene sin importar cómo esté configurado el servidor. El User-Agent siempre termina con la identidad del proyecto y una dirección donde se puede contactar a una persona. LRCLIB es un servicio gratuito y publica su API para que las máquinas la lean, y este servidor la lee bajo demanda, una llamada a la vez, en respuesta a algo que hayas pedido.

Cada resultado incluye el artista, el título y la dirección de su página en LRCLIB, y get_lyrics incluye attribution, los tres escritos en una sola línea.

Las letras de canciones son obra de sus autores y editores. Este proyecto no reclama derechos sobre ellas, no almacena ninguna base de datos de las mismas, no escribe nada en el disco y no contribuye nada a LRCLIB. Este servidor MCP es un proyecto no oficial, sin afiliación con LRCLIB.

Privacidad

Este servidor no recopila nada sobre ti y no envía nada a su autor. Se ejecuta en tu máquina, contacta a lrclib.net y a nada más, mantiene sus respuestas en memoria mientras se ejecuta y no escribe nada en el disco. PRIVACY.md indica qué lleva una solicitud y qué ajustes cambian algo de eso.

Desarrollo

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

Las pruebas se ejecutan contra fixtures generados y no realizan ninguna solicitud de red. La suite en vivo, npm run test:live, hace una solicitud por ruta y se ejecuta cada noche contra el propio servicio.

Contribuciones

Los errores, preguntas e ideas pertenecen a el rastreador de problemas. Las solicitudes de extracción son bienvenidas; abrir un problema primero ayuda a acordar la forma del cambio. Consulta CONTRIBUTING.md.

Licencia

MIT, ver LICENSE. Las letras pertenecen a sus autores y editores, y la base de datos a LRCLIB y sus contribuyentes.

mcp-lrclib (français)

Versión en inglés

LRCLIB es una base de datos de letras de canciones libre y abierta, alimentada por quienes la usan y ofrecida a todos sin clave ni cuenta. Contiene dos formas de letras: el texto simple de una canción, y la forma LRC, donde cada línea lleva el momento en que se canta, lo que sigue un display de karaoke o un panel de letras. Un título se clasifica por su nombre, su artista, su álbum y su duración, de modo que las diferentes versiones de una misma canción conviven allí.

Este servidor conecta un cliente de conversación a esta base. Se puede buscar un título por su nombre, su artista o su álbum, leer las letras simples de una canción, leer sus líneas con marcas de tiempo, y verificar la ficha de una versión antes de leerla. Sin clave de API, sin cuenta.

Instalación

Instalación en un clic

Claude Code

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

Claude Desktop, Cursor y cualquier cliente con formato de configuración estándar

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

Se requiere Node 24 o más reciente, y no hay que configurar ninguna variable de entorno.

Con Docker

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

-i mantiene la entrada estándar abierta, que es el canal del protocolo, y -t se omite porque un TTY reescribe el flujo. El contenedor necesita acceso HTTPS saliente a lrclib.net, y nada más: sin volúmenes, sin puertos, sin identificadores.

Bundle, sin npm

Descargue mcp-lrclib-2.0.1.mcpb desde la última publicación y ábralo. Un cliente que gestione bundles MCP lo instala solo, sin npm y sin archivo de configuración que modificar. El bundle incluye sus dependencias, por lo que nada se descarga en la instalación.

Lo que se puede pedir

«Encuéntrame las letras de Le Sud de Nino Ferrer.»
«Dame las letras con marcas de tiempo de Bohemian Rhapsody para seguir.»
«¿Qué versiones de Hallelujah hay en LRCLIB y cuál es su duración?»
«Léeme la segunda mitad de estas letras.»
«¿El título 3396226 tiene letras sincronizadas?»

El camino habitual va de una búsqueda a una lectura: search_tracks nombra un id, y get_lyrics retoma ese identificador.

Las herramientas

Herramienta	Lo que hace
`search_tracks`	Encuentra títulos por nombre, artista o álbum, con sus fichas.
`get_lyrics`	Lee las letras de un título, simples o con marcas de tiempo.
`get_track`	Lee la ficha de un título por su identificador, sin las letras.

LRCLIB clasifica un título por su ficha, por lo que una búsqueda alcanza una canción por su nombre, su artista o su álbum. Una palabra retenida del interior de una canción no encuentra nada.

`search_tracks`

Encuentra los títulos cuya ficha coincide, en una búsqueda libre o por campos. Varias versiones de una misma canción aparecen una al lado de la otra, y su álbum y su duración las distinguen.

Argumento	Tipo	Requerido	Lo que hace
`query`	cadena, de 1 a 200 caracteres	no	Búsqueda libre, por ejemplo `nino ferrer le sud`.
`track_name`	cadena, hasta 200 caracteres	no	Nombre de la canción, para una búsqueda por campos.
`artist_name`	cadena, hasta 200 caracteres	no	Nombre del artista, para una búsqueda por campos.
`album_name`	cadena, hasta 200 caracteres	no	Nombre del álbum, para acotar una búsqueda por campos.
`limit`	entero, de 1 a 50, por defecto `10`	no	Líneas a servir. LRCLIB devuelve hasta 20 por búsqueda.

Pase query, o uno de los tres campos.

En retorno: líneas que llevan id, que get_lyrics y get_track retoman; track_name y artist_name; album_name y duration_seconds, que distinguen dos versiones de una misma canción; instrumental; has_plain_lyrics y has_synced_lyrics, que permiten verificar la existencia de las líneas con marcas de tiempo antes de pedirlas; y source_url. También vienen result_count y total_available, los títulos que LRCLIB sirvió antes de aplicar limit. album_name y duration_seconds valen null en un título clasificado sin ellos, y las líneas no llevan ninguna letra: get_lyrics las lee.

`get_lyrics`

Lee las letras de un título, en texto simple o en líneas LRC que llevan el momento en que cada una se canta. Las letras largas se sirven por tramos, cortados en un fin de línea.

Argumento	Tipo	Requerido	Lo que hace
`id`	entero, positivo	no	El identificador LRCLIB devuelto por `search_tracks`.
`artist_name`	cadena, hasta 200 caracteres	no	Nombre del artista, coincidencia exacta. Necesario sin `id`.
`track_name`	cadena, hasta 200 caracteres	no	Nombre de la canción, coincidencia exacta. Necesario sin `id`.
`album_name`	cadena, hasta 200 caracteres	no	Nombre del álbum, para elegir entre versiones.
`duration_seconds`	número, positivo	no	Duración del título, para elegir entre versiones de longitudes diferentes.
`format`	`plain`, `synced` o `both`, por defecto `plain`	no	La forma de las letras a servir.
`max_chars`	entero, de 200 a 20000, por defecto `6000`	no	Caracteres de texto a servir en esta llamada.
`offset`	entero, 0 o más, por defecto `0`	no	Posición en caracteres donde retomar.

En retorno: status, que vale ok, instrumental para un título sin letras que cantar, o no_lyrics para un título clasificado sin ellas; track con su identificador, su nombre, su artista, su álbum, su duración y su source_url; plain_lyrics; synced_lyrics en texto LRC bruto y synced_lines en lista de { time_seconds, text }, con synced_lines_truncated cuando el tramo las ha cortado. La lectura se describe con paginated_form, total_chars, returned_chars, offset, next_offset y truncated: vuelva a dar next_offset para continuar, y null marca el final. attribution es la línea a citar cuando se muestran las letras. Un status a instrumental es una respuesta completa.

`get_track`

Lee la ficha de un título desde su identificador, sin las letras. Confirma una versión antes de pedir las letras, y resuelve un identificador venido de un intercambio anterior.

Argumento	Tipo	Requerido	Lo que hace
`id`	entero, positivo	sí	El identificador LRCLIB devuelto por `search_tracks`.

En retorno: track, que lleva los campos de una línea de búsqueda, y duration_formatted en la forma m:ss, null para un título clasificado sin duración. has_plain_lyrics y has_synced_lyrics dicen qué formas get_lyrics puede servir.

Configuración

Cada variable es opcional. Se colocan en el bloque env de la configuración del cliente.

Variable	Por defecto	Lo que hace
`LRCLIB_USER_AGENT`	la identidad del proyecto	Nombra tu aplicación ante LRCLIB, con una dirección donde contactar a una persona.
`LRCLIB_MIN_INTERVAL_MS`	`500`	Intervalo entre dos solicitudes, de 200 a 60000. Un valor bajo el mínimo se rechaza en favor de este.
`LRCLIB_TIMEOUT_MS`	`15000`	Tiempo de espera de una solicitud, de 1000 a 120000.
`LRCLIB_MAX_RETRIES`	`3`	Intentos después de un fallo pasajero, de 0 a 10.
`LRCLIB_CACHE_TTL_MS`	`900000`	Duración durante la cual una respuesta permanece en memoria, de 0 a 86400000.
`LRCLIB_CACHE_MAX_ENTRIES`	`200`	Respuestas guardadas en memoria a la vez, de 0 a 10000.
`LRCLIB_LOG_LEVEL`	`error`	`silent`, `error`, `info` o `debug`, escrito en la salida de error.

Un valor fuera de su rango cae en el valor por defecto, y la razón se escribe en la salida de error.

Errores

Cada fallo lleva uno de los seis códigos, un mensaje y, cuando ayuda, una indicación del siguiente paso.

Código	Qué ocurrió	Qué hacer
`not_found`	LRCLIB respondió y no contiene este título.	Verifique la ortografía con `search_tracks`.
`invalid_input`	Los argumentos fueron rechazados antes de cualquier solicitud.	Lea el mensaje, que nombra el argumento.
`rate_limited`	LRCLIB pide a este cliente que reduzca la velocidad.	Espere los segundos indicados y vuelva a llamar con los mismos argumentos. El título sigue ahí.
`upstream_error`	LRCLIB respondió en un formato que este cliente no lee.	Repórtelo en el seguimiento de incidentes.
`network_error`	La solicitud no se completó.	Reintente en breve.
`timeout`	La solicitud superó su tiempo límite.	Aumente `LRCLIB_TIMEOUT_MS`, o solicite un `max_chars` más pequeño.

Como biblioteca

La capa que lee LRCLIB se publica sola, con su ritmo, su caché y sus errores, sin protocolo adjunto.

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 y getById responden cada uno { data, cached }, y lanzan un error con uno de los seis códigos. El intervalo mínimo entre dos solicitudes también se aplica aquí.

Ritmo y atribución

Las solicitudes salen una a una con un intervalo mínimo entre ellas, y este intervalo se mantiene sin importar la configuración. El User-Agent siempre termina con la identidad del proyecto y una dirección para contactar a una persona. LRCLIB es un servicio gratuito y publica su API para ser leída por máquinas, y este servidor la lee bajo demanda, una llamada a la vez, en respuesta a lo que usted ha solicitado.

Cada resultado incluye el artista, el título y la dirección de su página en LRCLIB, y get_lyrics incluye attribution, estos tres elementos escritos en una línea.

Las letras son obra de sus autores y de sus editores. Este proyecto no reclama ningún derecho sobre ellas, no incluye ninguna base de letras, no escribe nada en el disco y no contribuye nada a LRCLIB. Este MCP es un proyecto no oficial, sin afiliación con LRCLIB.

Privacidad

Este servidor no recopila nada sobre usted y no envía nada a su autor. Se ejecuta en su máquina, solo adjunta lrclib.net, guarda sus respuestas en memoria mientras se ejecuta, y no escribe nada en el disco. PRIVACY.md dice qué lleva una solicitud y qué ajustes cambian eso.

Desarrollo

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

Las pruebas se ejecutan sobre fixtures generados y no emiten ninguna solicitud. La suite en vivo, npm run test:live, emite una solicitud por ruta y se ejecuta cada noche contra el propio servicio.

Contribuir

Las anomalías, las preguntas y las ideas tienen su lugar en el seguimiento de incidentes. Las propuestas de modificación son bienvenidas; abrir un ticket primero ayuda a ponerse de acuerdo sobre la forma del cambio. Ver CONTRIBUTING.md.

Licencia

MIT, ver LICENSE. Las letras pertenecen a sus autores y a sus editores, y la base a LRCLIB y a sus contribuyentes.