setlist-mcp

Un servidor MCP que permite a Claude encontrar setlists de setlist.fm de conciertos a los que hayas asistido.

Pregunta «Vi a The Cure en Wellington en agosto de 1992 — ¿qué tocaron?» y Claude identifica al artista, busca en setlist.fm y te devuelve las canciones en orden.

Características

• find_setlists — busca por artista, ciudad y fecha. Devuelve una lista compacta de conciertos coincidentes con sus IDs de setlist, recintos y número de canciones.

• get_setlist — obtiene un setlist completo: cada canción en orden, agrupada en sets y bises, con notas sobre versiones y apariciones de invitados.

• Indulgente con las fechas. La búsqueda cubre el año alrededor de la fecha que indiques y ordena los resultados según su cercanía, así que un día mal recordado aún encuentra el concierto.

• Indulgente con los nombres de artistas. Los nombres se resuelven mediante MusicBrainz, por lo que los pequeños errores ortográficos suelen funcionar. Los nombres ambiguos devuelven alternativas.

• Cuidado con los límites de frecuencia. Las solicitudes se serializan y se espacian, los 429 se reintentan con retroceso y las respuestas se guardan en caché. Las búsquedas tardan unos segundos por diseño.

Related MCP server: MusicBrainz MCP Server

Instalación

git clone git@github.com:adrianparker/setlist-mcp.git
cd setlist-mcp
npm install
cp .env.example .env

A continuación, edita .env y define SETLISTFM_API_KEY. Solicita una clave en la configuración de API de setlist.fm — es gratuita y requiere una cuenta de setlist.fm.

Configurar MUSICBRAINZ_CONTACT con tu dirección de correo es de buena educación: MusicBrainz pide que los clientes identifiquen un contacto en su User-Agent, y limita con más dureza a los clientes que parecen anónimos.

Registro con Claude Code

claude mcp add setlist-mcp --scope user -- node /full/path/to/setlist-mcp/src/index.js

O añádelo al .mcp.json de un proyecto:

{
  "mcpServers": {
    "setlist-mcp": {
      "command": "node",
      "args": ["/full/path/to/setlist-mcp/src/index.js"]
    }
  }
}

En la configuración del cliente no van secretos: el servidor lee .env desde su propio directorio, así que funciona desde cualquier directorio desde el que el cliente lo lance.

Reinicia Claude Code y comprueba que se ha conectado con /mcp.

Uso

Una vez registrado, solo tienes que preguntar en lenguaje natural:

Vi a Villainy en Tauranga en marzo de 2026, ¿cuál fue el setlist?

Claude llamará a find_setlists, elegirá el concierto que coincida y luego llamará a get_setlist.

Para comprobar el servidor directamente sin un cliente:

npx @modelcontextprotocol/inspector node src/index.js

Configuración

Límites de frecuencia

setlist.fm no publica sus límites de frecuencia. Los informes de la comunidad sitúan el nivel estándar en aproximadamente 2 solicitudes por segundo y 1440 al día, por lo que los valores predeterminados aquí —una solicitud cada 1,1 segundos— se encuentran cómodamente dentro del extremo más lento de eso. Las solicitudes se serializan mediante una cola, de modo que las llamadas concurrentes a las herramientas esperan su turno en lugar de dispararse. Un 429 frena toda la cola, respetando Retry-After cuando el servidor lo envía.

El límite diario no es una cuota diaria real. Se mantiene en memoria, por lo que se restablece cada vez que el cliente MCP reinicia el servidor. Trátalo como un cortacircuitos contra un bucle descontrolado, no como un requisito de cumplimiento. El intervalo mínimo es lo que realmente protege tu clave: a 1,1 s por solicitud, alcanzar las 1440 solicitudes llevaría 26 minutos de consultas continuas.

Las respuestas se guardan en memoria caché —artistas durante 24 horas, búsquedas durante 1 hora, detalles de setlist durante 6 horas—, así que las preguntas repetidas sobre el mismo concierto no cuestan nada.

Desarrollo

Ejecutar pruebas

npm test
npm run test:watch

Ninguna prueba toca las APIs reales: test/setup.js instala un global.fetch que lanza una excepción, y las pruebas lo sustituyen explícitamente.

Cobertura

npm run coverage

Lint

npm run lint

Una nota sobre setlist.fm

La API de setlist.fm es gratuita solo para uso no comercial; consulta sus términos de API. Ambas herramientas devuelven la URL de setlist.fm para cada resultado, de modo que se pueda enlazar de vuelta.

Los datos de los setlists son aportados por los usuarios de setlist.fm. Los conciertos pueden faltar, estar incompletos o tener una fecha incorrecta.

Licencia

MIT