Bandcamp MCP (bandcamp-mcp)

bandcamp-mcp

Explora Bandcamp hablando con Claude: sigue el catálogo de un sello, mira qué hay nuevo bajo una etiqueta, consulta la lista de canciones y el precio de un álbum, y descubre quién hizo realmente la pista 7 de esa compilación. bandcamp-mcp es un servidor local de MCP — la forma en que un asistente de IA accede a herramientas en tu máquina — por lo que cualquier cliente MCP puede usarlo: Claude Desktop, Claude Code, Cursor, VS Code. Sin cuenta, sin clave de API, nada que configurar.

Estado: experimental. Pre-1.0 y en desarrollo activo: una versión menor puede cambiar el comportamiento o romper la compatibilidad, un parche nunca lo hace. Solo se admite la última versión.

No está afiliado, respaldado ni patrocinado por Bandcamp.

Lo que puedes preguntar

• "¿Qué hay en el catálogo de Sacred Bones y de quién es cada lanzamiento?"
• "Encuentra el álbum Cathedral de John Carpenter y léeme la lista de canciones con las duraciones."
• "Muéstrame diez lanzamientos nuevos bajo la etiqueta drum-bass, luego abre cada uno y dime su sello y fecha de lanzamiento."
• "¿Esa compilación es de varios artistas? Dime quién hizo cada pista."
• "¿Cuánto cuesta este álbum y es de precio libre?"
• "Encuentra ese enlace de Bandcamp que me envió un amigo y dime qué más ha lanzado el artista."

Las respuestas provienen de las propias páginas públicas de Bandcamp, obtenidas en vivo — una solicitud por llamada de herramienta que haga el asistente. El servidor solo lee; nunca compra, descarga ni toca una cuenta, y no tiene ningún campo a través del cual un enlace de transmisión o descarga pueda llegar a ti.

Instalación

npx es toda la instalación: tu cliente MCP inicia el servidor bajo demanda y recoge las correcciones la próxima vez que se lance.

Claude Code:

claude mcp add bandcamp -- npx -y bandcamp-mcp

Claude Desktop (Configuración → Desarrollador → Editar configuración), o cualquier cliente MCP que inicie un servidor stdio desde un comando:

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

Cursor: instalar en Cursor, o añade el mismo bloque JSON a ~/.cursor/mcp.json.

VS Code (modo agente Copilot): instalar en VS Code, o ejecuta code --add-mcp '{"name":"bandcamp","command":"npx","args":["-y","bandcamp-mcp"]}'.

Plugin de Claude Code: este repositorio también es un plugin (.claude-plugin/plugin.json), por lo que /plugin puede instalarlo una vez que esté listado.

Requisitos y qué se prueba realmente

Node.js 20 o más reciente (se recomienda 22 LTS); Node 18 está al final de su vida útil y una dependencia del SDK de MCP requiere 20. Cada push ejecuta la suite de pruebas en Node 20, 22 y 24, luego empaqueta el paquete, lo instala en un proyecto vacío y lo inicia mediante un handshake de MCP en Linux, macOS y Windows, en cada una de esas versiones de Node. No se afirma nada más: otras plataformas pueden funcionar, pero nadie las ha medido.

Bandcamp en sí no tiene una API versionada. Lo que el servidor lee es lo que bandcamp.com sirve hoy, por eso una prueba de humo se ejecuta contra el sitio en vivo a diario (insignia arriba) y por eso una herramienta puede empezar a fallar sin aviso — ver Cómo funciona esto.

Para fijar una versión, usa bandcamp-mcp@<version> (p. ej. npx -y bandcamp-mcp@0.1.0). Un npx -y bandcamp-mcp sin fijar recoge las correcciones la próxima vez que tu cliente lo inicie; una copia fijada o instalada globalmente no lo hace (ver Limitaciones conocidas).

Windows

Los clientes MCP con interfaz gráfica en Windows a menudo no pueden iniciar npx directamente, porque es un script de .cmd. Envuélvelo en cmd /c:

{
  "mcpServers": {
    "bandcamp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "bandcamp-mcp"]
    }
  }
}

Con Claude Code:

claude mcp add bandcamp -- cmd /c npx -y bandcamp-mcp

CI verifica este comando: en windows-latest, el trabajo package instala el paquete empaquetado en un proyecto y ejecuta cmd /c npx -y bandcamp-mcp allí mediante un handshake de MCP (initialize, luego tools/list). Allí, npx encuentra la copia instalada en lugar de descargarla, por lo que la verificación cubre cómo se inicia el servidor en Windows, no la descarga.

Solución de problemas: "servidor desconectado" / spawn npx ENOENT

Los clientes MCP lanzados desde interfaz gráfica a menudo inician servidores con un PATH mínimo que omite los shims de nvm/volta, incluso cuando npx -y bandcamp-mcp funciona en tu terminal. Instala el paquete globalmente y apunta el cliente a rutas absolutas en su lugar:

npm install -g bandcamp-mcp
which node                                         # the "command" below (Windows: where node)
echo "$(npm root -g)/bandcamp-mcp/dist/index.js"   # the "args" entry below

{
  "mcpServers": {
    "bandcamp": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/node_modules/bandcamp-mcp/dist/index.js"]
    }
  }
}

En Windows, cada barra invertida en las rutas JSON debe duplicarse, p. ej. C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\bandcamp-mcp\\dist\\index.js. Una instalación global no se actualiza sola: ejecuta npm install -g bandcamp-mcp@latest para recoger una corrección.

Si tu red bloquea el registro npm

npx busca el paquete en registry.npmjs.org cada vez que tu cliente inicia el servidor. Si el registro está bloqueado, o solo es alcanzable a veces, ejecuta npm install -g bandcamp-mcp una vez mientras tengas acceso y usa la configuración de ruta absoluta anterior, que se inicia sin el registro.

Cómo funciona esto y por qué puede romperse

Bandcamp no tiene una API de catálogo pública, por lo que cada llamada de herramienta hace solicitudes en vivo a los mismos endpoints que usa el propio sitio web de Bandcamp:

• bandcamp_search: el endpoint JSON detrás del cuadro de búsqueda de Bandcamp (/api/bcsearch_public_api/1/autocomplete_elastic);
• bandcamp_browse_tag: el endpoint JSON detrás de bandcamp.com/discover (/api/discover/1/discover_web);
• bandcamp_get_album y bandcamp_get_track: la página pública de lanzamiento o pista, leída principalmente de su bloque JSON-LD de schema.org, con etiquetas del marcado de la página;
• bandcamp_get_artist: la página /music del artista o sello, leída de su marcado.

Ninguno de estos es una API publicada y versionada. Bandcamp puede cambiarlos en cualquier momento y sin previo aviso, y una herramienta entonces deja de funcionar hasta que este proyecto publique una corrección. Cuando eso sucede, la herramienta lo dice ("El formato de respuesta de Bandcamp parece haber cambiado", o que recibió una verificación de bot en lugar de datos) y enlaza a la página de problemas. Una prueba de humo diaria (insignia arriba) ejecuta el código de cliente de cada herramienta contra páginas en vivo de Bandcamp e informa fallos a un problema de seguimiento. Las notas de los endpoints están en docs/bandcamp-endpoints.md.

• Solo metadatos. Los lanzamientos se identifican por slug, y los esquemas de resultados (src/client/types.ts) no tienen campo para enlaces de transmisión, descarga o compra, por lo que los enlaces de audio firmados en las páginas de Bandcamp no pueden pasar. (Los campos de texto libre son las propias palabras de los artistas y pueden mencionar enlaces).
• Sin caché ni republicación. Cada llamada de herramienta se obtiene en vivo. Nada se almacena; los resultados van a tu cliente MCP y a ningún otro lugar.
• Sin telemetría. Ni este paquete ni Venut Technologies recopilan nada; lo que el servidor lee, envía y almacena se enumera en PRIVACY.md. Pero cada llamada de herramienta es una solicitud desde tu máquina directamente a Bandcamp, que ve tu dirección IP, qué pediste y cuándo. Las solicitudes también dicen de dónde vienen, con el User-Agent Mozilla/5.0 (compatible; bandcamp-mcp/<version>; +https://github.com/Venut-Technologies/bandcamp-mcp), para que no parezcan una visita de navegador.
• Suave por diseño. Como máximo 3 solicitudes en vuelo, con al menos 150 ms de separación, un tiempo de espera de 7 segundos y un reintento para un tiempo de espera, una falla a nivel de transporte (un reinicio o socket cerrado, un error de DNS o TLS), 5xx o 429 (respetando un Retry-After de hasta 5 s). Solo se obtienen los hosts bandcamp.com y *.bandcamp.com: los redireccionamientos se siguen manualmente (como máximo 3) y cada destino se verifica contra esa lista.

El robots.txt de Bandcamp cierra /api/ a los rastreadores, lo que cubre el endpoint de búsqueda, y permite explícitamente el de exploración. Este servidor no es un rastreador: obtiene una página por llamada de herramienta que hagas, no sigue enlaces y no almacena nada. Esa lectura, el argumento en contra y el compromiso de cambiar o eliminar una herramienta si Bandcamp se opone están todos registrados en CONTRIBUTING.md.

El repositorio (no el paquete npm) contiene páginas y respuestas de API capturadas de Bandcamp como fixtures de prueba, con las URL firmadas de transmisión y descarga redactadas, las identidades y el texto libre reemplazados por otros inventados, y cada página recortada al marcado que leen los analizadores.

¿Encontraste un error o tienes una preocupación sobre abuso? Abre un problema: https://github.com/Venut-Technologies/bandcamp-mcp/issues

Los problemas de seguridad van de forma privada a security@venut.tech; ver SECURITY.md.

Herramientas

Herramienta	Entrada	Devuelve
bandcamp_search	query (1–200 caracteres); type: all (predeterminado), album, artist, track o label	Coincidencias clasificadas, cada una {type, name, artist, slug}. Los artistas y sellos se distinguen por el indicador is_label de Bandcamp en cada resultado.
bandcamp_get_album	slug, p. ej. johncarpentermusic/album/cathedral	Título, artista, fecha de lanzamiento, sello, etiquetas, descripción, el precio digital (priceText es el mínimo, con priceCurrency; isNameYourPrice) y la lista de canciones: el artista de cada pista (compilaciones), posición, duración y slug.
bandcamp_get_artist	slug: el subdominio del artista o sello, p. ej. sacredbonesrecords	Nombre, ubicación, biografía y discografía: como máximo 100 entradas {title, slug, type, artist} (en una página de sello, artist es el artista propio de cada lanzamiento). discographyTotal cuenta todos los lanzamientos; discographyTruncated indica si algunos se omitieron. Sin etiquetas.
bandcamp_get_track	slug, p. ej. johncarpentermusic/track/primeval	Cualquier página de pista, ya sea una pista de un álbum o un sencillo independiente: título, artista, duración, etiquetas, descripción y album {title, slug}, el álbum al que pertenece (en un sencillo independiente: el propio título de la pista con slug: null; null cuando la página no nombra ningún álbum).
bandcamp_browse_tag	tag (opcional): un slug de etiqueta de Bandcamp como ambient, drum-bass o русский-рок; sort: top (predeterminado) o new; cursor (opcional)	Hasta 20 lanzamientos por página, cada uno {type, name, artist, slug}, más nextCursor para la siguiente página. Omite tag para un listado sin filtrar en Bandcamp. Una etiqueta de forma libre se normaliza a forma de slug (Drum & Bass → drum-bass). Un cursor solo funciona con la etiqueta y el orden del que proviene.

Cada slug es un identificador de Bandcamp copiado de un resultado anterior (<subdomain>/album/<item>, <subdomain>/track/<item> o un subdominio simple para un artista o sello), nunca un nombre para mostrar. Las herramientas no aceptan URL: una URL de Bandcamp https://<subdomain>.bandcamp.com/album/<item> se convierte en el slug <subdomain>/album/<item>, y las descripciones de las herramientas se lo indican al modelo. Un resultado cuyo slug es null no se puede consultar (ver dominios personalizados a continuación).

Limitaciones conocidas

• Proyecto de un solo mantenedor, de mejor esfuerzo, sin SLA. La prueba de humo diaria es monitoreo, no una garantía de soporte.
• Inyección de prompts. Nombres, títulos, biografías, descripciones y etiquetas son escritos por usuarios de Bandcamp, y cualquiera puede publicar en Bandcamp. Este servidor decodifica entidades, elimina marcado, caracteres de control e invisibles, y limita su longitud, y cada descripción de herramienta le dice al modelo que los trate como datos, nunca como instrucciones. Eso reduce el riesgo de que una biografía manipulada dirija a tu asistente; no lo elimina.
• Las instalaciones fijadas y globales no se auto-reparan. Cuando Bandcamp cambia algo y se publica una corrección, solo las configuraciones no fijadas de npx la reciben automáticamente. Una copia fijada a @x.y.z o instalada con npm install -g sigue fallando, y el error no puede indicarte que existe una corrección. Si una herramienta informa que el formato de Bandcamp cambió, revisa los issues y el CHANGELOG, y luego actualiza.
• Dominios personalizados. El servidor solo obtiene hosts de bandcamp.com y *.bandcamp.com, como protección contra ser dirigido a otros servidores (SSRF). Un lanzamiento, artista o sello que Bandcamp lista bajo su propio dominio (p. ej. ilistentojohn.com, visto en una búsqueda de "carpenter") regresa con slug: null y no se puede consultar desde ese resultado, y un artista cuyo subdominio redirige a su propio dominio se reporta como no encontrado, con esa razón.
• Sin etiquetas para artistas y sellos. Sus páginas no contienen ninguna, por lo que bandcamp_get_artist devuelve ninguna; bandcamp_get_album tiene las etiquetas de un lanzamiento.
• El label de un álbum puede nombrar a la cuenta anfitriona. Cuando la página no indica un sello discográfico, el campo recurre a la cuenta de Bandcamp que publicó el lanzamiento. Eso es correcto para la página de un sello, y el servidor lo suprime cuando la cuenta es uno de los artistas acreditados — pero en un lanzamiento auto-publicado con un crédito de múltiples artistas cuyo nombre de cuenta no comparte nada con él (una banda, un estudio de juegos, un colectivo), la cuenta se reporta como el sello.
• Los catálogos largos se cortan en 100 lanzamientos en bandcamp_get_artist.
• Cancelar no detiene la solicitud. Una llamada de herramienta que tu cliente cancela aún termina su solicitud a Bandcamp en segundo plano (limitada por el tiempo de espera); v1 no transmite la cancelación.
• Sin orden "recomendado". Bandcamp personaliza eso solo para cuentas de fans con sesión iniciada, y este proyecto es intencionalmente sin credenciales, por lo que bandcamp_browse_tag ofrece top y new.
• Fuera de alcance: iniciar sesión, tu colección o lista de deseos, compras, datos de ventas y transporte remoto (HTTP/SSE). El servidor se ejecuta localmente solo a través de stdio.

Principios

Lo que este servidor garantiza y lo que se niega a hacer — anónimo y de solo lectura, slugs en lugar de URLs, ningún campo que pueda llevar un enlace de stream o descarga, un error honesto cuando Bandcamp cambia — está documentado, con el código y las pruebas que lo respaldan, en PRINCIPLES.md.

Contribuciones

Consulta CONTRIBUTING.md.

Licencia

MIT; consulta LICENSE.