Bandcamp MCP (bandcamp-mcp)

bandcamp-mcp

Explore o Bandcamp conversando com o Claude: siga o catálogo de uma gravadora, veja o que há de novo em uma tag, consulte a lista de faixas e o preço de um álbum e descubra quem realmente fez a faixa 7 daquela compilação. bandcamp-mcp é um servidor MCP local — a forma pela qual um assistente de IA acessa ferramentas na sua máquina — então qualquer cliente MCP pode usá-lo: Claude Desktop, Claude Code, Cursor, VS Code. Sem conta, sem chave de API, nada para configurar.

Status: experimental. Pré-1.0 e em desenvolvimento ativo: uma versão menor pode mudar o comportamento ou quebrar a compatibilidade, um patch nunca quebra. Apenas a versão mais recente é suportada.

Não é afiliado, endossado ou patrocinado pelo Bandcamp.

O que você pode perguntar

• "O que há no catálogo da Sacred Bones e de quem é cada lançamento?"
• "Encontre o álbum Cathedral do John Carpenter e leia a lista de faixas com as durações."
• "Mostre-me dez novos lançamentos sob a tag drum-bass, depois abra cada um e me diga a gravadora e a data de lançamento."
• "Essa compilação é de vários artistas? Diga-me quem fez cada faixa."
• "Quanto custa este álbum e ele é pague-quanto-quiser?"
• "Encontre aquele link do Bandcamp que um amigo me enviou e diga-me o que mais o artista lançou."

As respostas vêm das próprias páginas públicas do Bandcamp, buscadas ao vivo — uma requisição por chamada de ferramenta que o assistente faz. O servidor apenas lê; ele nunca compra, baixa ou toca em uma conta, e não possui nenhum campo pelo qual um link de streaming ou download possa chegar até você.

Instalação

npx é a instalação completa: seu cliente MCP inicia o servidor sob demanda e aplica correções na próxima vez que for iniciado.

Claude Code:

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

Claude Desktop (Configurações → Desenvolvedor → Editar Configuração), ou qualquer cliente MCP que inicie um servidor stdio a partir de um comando:

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

Cursor: instalar no Cursor, ou adicione o mesmo bloco JSON em ~/.cursor/mcp.json.

VS Code (modo agente do Copilot): instalar no VS Code, ou execute code --add-mcp '{"name":"bandcamp","command":"npx","args":["-y","bandcamp-mcp"]}'.

Plugin do Claude Code: este repositório também é um plugin (.claude-plugin/plugin.json), então /plugin pode instalá-lo assim que estiver listado.

Requisitos e o que é realmente testado

Node.js 20 ou mais recente (22 LTS recomendado); o Node 18 está em fim de vida útil e uma dependência do SDK MCP exige a versão 20. Cada push executa a suíte de testes no Node 20, 22 e 24, depois empacota o pacote, instala-o em um projeto vazio e o inicia por meio de um handshake MCP no Linux, macOS e Windows, em cada uma dessas versões do Node. Nada mais é garantido: outras plataformas podem funcionar, mas ninguém as mediu.

O próprio Bandcamp não possui uma API versionada. O que o servidor lê é o que bandcamp.com serve hoje, por isso um teste de fumaça é executado contra o site ao vivo diariamente (selo acima) e por isso uma ferramenta pode começar a falhar sem aviso — veja Como isso funciona.

Para fixar uma versão, use bandcamp-mcp@<version> (ex.: npx -y bandcamp-mcp@0.1.0). Um npx -y bandcamp-mcp sem versão fixada aplica correções na próxima vez que seu cliente o iniciar; uma cópia fixada ou instalada globalmente não (veja Limitações conhecidas).

Windows

Clientes MCP com interface gráfica no Windows muitas vezes não conseguem iniciar npx diretamente, porque é um script .cmd. Envolva-o em cmd /c:

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

Com o Claude Code:

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

O CI verifica este comando: no windows-latest, o job package instala o pacote empacotado em um projeto e executa cmd /c npx -y bandcamp-mcp lá por meio de um handshake MCP (initialize e depois tools/list). Nesse caso, o npx encontra a cópia instalada em vez de baixá-la, então a verificação cobre como o servidor inicia no Windows, não o download.

Solução de problemas: "servidor desconectado" / spawn npx ENOENT

Clientes MCP iniciados por interface gráfica frequentemente iniciam servidores com um PATH mínimo que deixa de fora os shims do nvm/volta, mesmo quando npx -y bandcamp-mcp funciona no seu terminal. Instale o pacote globalmente e aponte o cliente para caminhos absolutos:

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"]
    }
  }
}

No Windows, cada barra invertida nos caminhos JSON deve ser duplicada, ex.: C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\bandcamp-mcp\\dist\\index.js. Uma instalação global não se atualiza sozinha: execute npm install -g bandcamp-mcp@latest para aplicar uma correção.

Se sua rede bloqueia o registro npm

npx procura o pacote em registry.npmjs.org sempre que seu cliente inicia o servidor. Se o registro estiver bloqueado, ou apenas às vezes acessível, execute npm install -g bandcamp-mcp uma vez enquanto tiver acesso e use a configuração de caminho absoluto acima, que inicia sem o registro.

Como isso funciona e por que pode quebrar

O Bandcamp não possui uma API pública de catálogo, então cada chamada de ferramenta faz requisições ao vivo para os mesmos endpoints que o próprio site do Bandcamp usa:

• bandcamp_search: o endpoint JSON por trás da caixa de busca do Bandcamp (/api/bcsearch_public_api/1/autocomplete_elastic);
• bandcamp_browse_tag: o endpoint JSON por trás do bandcamp.com/discover (/api/discover/1/discover_web);
• bandcamp_get_album e bandcamp_get_track: a página pública do lançamento ou da faixa, lida principalmente do bloco JSON-LD do schema.org, com tags do markup da página;
• bandcamp_get_artist: a página /music do artista ou da gravadora, lida do markup dela.

Nenhum desses é uma API publicada e versionada. O Bandcamp pode alterá-los a qualquer momento e sem aviso, e uma ferramenta então para de funcionar até que este projeto publique uma correção. Quando isso acontece, a ferramenta avisa ("o formato de resposta do Bandcamp parece ter mudado", ou que recebeu uma verificação de bot em vez de dados) e fornece links para a página de issues. Um teste de fumaça diário (selo acima) executa o código de cliente de cada ferramenta contra páginas ao vivo do Bandcamp e relata falhas em uma issue de rastreamento. As notas sobre os endpoints estão em docs/bandcamp-endpoints.md.

• Apenas metadados. Os lançamentos são identificados por slug, e os esquemas de resultado (src/client/types.ts) não possuem campo para links de streaming, download ou compra, então os links de áudio assinados nas páginas do Bandcamp não podem passar. (Campos de texto livre são as próprias palavras dos artistas e podem mencionar links.)
• Sem cache ou republicação. Cada chamada de ferramenta é buscada ao vivo. Nada é armazenado; os resultados vão para seu cliente MCP e para nenhum outro lugar.
• Sem telemetria. Nem este pacote nem a Venut Technologies coletam nada; o que o servidor lê, envia e armazena está listado em PRIVACY.md. Mas cada chamada de ferramenta é uma requisição da sua máquina direto para o Bandcamp, que vê seu endereço IP, o que você pediu e quando. As requisições também informam de onde vêm, com o User-Agent Mozilla/5.0 (compatible; bandcamp-mcp/<version>; +https://github.com/Venut-Technologies/bandcamp-mcp), para que não pareçam uma visita de navegador.
• Gentil por design. No máximo 3 requisições em andamento, com pelo menos 150 ms de intervalo, um timeout de 7 segundos e uma nova tentativa para timeout, falha no nível de transporte (reset ou socket fechado, erro de DNS ou TLS), 5xx ou 429 (respeitando um Retry-After de até 5 s). Apenas os hosts bandcamp.com e *.bandcamp.com são buscados: redirecionamentos são seguidos manualmente (no máximo 3) e cada destino é verificado contra essa lista.

O robots.txt do Bandcamp fecha /api/ para rastreadores, o que cobre o endpoint de busca, e permite explicitamente o de navegação. Este servidor não é um rastreador: ele busca uma página por chamada de ferramenta que você faz, não segue links e não armazena nada. Essa leitura, o argumento contra ela e o compromisso de mudar ou remover uma ferramenta se o Bandcamp se opuser estão todos registrados em CONTRIBUTING.md.

O repositório (não o pacote npm) contém páginas e respostas de API capturadas do Bandcamp como fixtures de teste, com as URLs assinadas de streaming e download redigidas, as identidades e o texto livre substituídos por inventados, e cada página reduzida ao markup que os parsers leem.

Encontrou um bug ou tem uma preocupação sobre abuso? Por favor, abra uma issue: https://github.com/Venut-Technologies/bandcamp-mcp/issues

Problemas de segurança vão em particular para security@venut.tech; veja SECURITY.md.

Ferramentas

Ferramenta	Entrada	Retorna
bandcamp_search	query (1–200 caracteres); type: all (padrão), album, artist, track ou label	Correspondências classificadas, cada uma com {type, name, artist, slug}. Artistas e gravadoras são diferenciados pelo sinalizador is_label do Bandcamp em cada resultado.
bandcamp_get_album	slug, ex.: johncarpentermusic/album/cathedral	Título, artista, data de lançamento, gravadora, tags, descrição, o preço digital (priceText é o mínimo, com priceCurrency; isNameYourPrice) e a lista de faixas: o artista de cada faixa (compilações), posição, duração e slug.
bandcamp_get_artist	slug: o subdomínio do artista ou da gravadora, ex.: sacredbonesrecords	Nome, localização, biografia e discografia: no máximo 100 entradas {title, slug, type, artist} (em uma página de gravadora, artist é o artista de cada lançamento). discographyTotal conta todos os lançamentos; discographyTruncated indica se alguns foram cortados. Sem tags.
bandcamp_get_track	slug, ex.: johncarpentermusic/track/primeval	Qualquer página de faixa, seja uma faixa de álbum ou um single avulso: título, artista, duração, tags, descrição e album {title, slug}, o álbum ao qual pertence (em um single avulso: o próprio título da faixa com slug: null; null quando a página não nomeia nenhum álbum).
bandcamp_browse_tag	tag (opcional): um slug de tag do Bandcamp como ambient, drum-bass ou русский-рок; sort: top (padrão) ou new; cursor (opcional)	Até 20 lançamentos por página, cada um com {type, name, artist, slug}, além de nextCursor para a próxima página. Omita tag para uma listagem sem filtro em todo o Bandcamp. Uma tag de forma livre é normalizada para a forma de slug (Drum & Bass → drum-bass). Um cursor só funciona com a tag e a ordenação de onde veio.

Cada slug é um identificador do Bandcamp copiado de um resultado anterior (<subdomain>/album/<item>, <subdomain>/track/<item> ou um subdomínio simples para um artista ou gravadora), nunca um nome de exibição. As ferramentas não aceitam URLs: uma URL do Bandcamp https://<subdomain>.bandcamp.com/album/<item> vira o slug <subdomain>/album/<item>, e as descrições das ferramentas informam o modelo sobre isso. Um resultado cujo slug é null não pode ser consultado (veja domínios personalizados abaixo).

Limitações conhecidas

• Projeto de mantenedor único, com esforço de boa-fé e sem SLA. O teste de fumaça diário é monitoramento, não uma garantia de suporte.
• Injeção de prompt. Nomes, títulos, bios, descrições e tags são escritos por usuários do Bandcamp, e qualquer pessoa pode publicar no Bandcamp. Este servidor decodifica entidades, remove marcação e caracteres de controle e invisíveis, e limita seu comprimento, e cada descrição de ferramenta diz ao modelo para tratá-los como dados, nunca como instruções. Isso reduz o risco de uma bio manipulada desviar seu assistente; não o elimina.
• Instalações fixadas (pinned) e globais não se auto-corrigem. Quando o Bandcamp muda algo e uma correção é lançada, apenas instalações não fixadas de npx recebem automaticamente. Uma cópia fixada em @x.y.z ou instalada com npm install -g continua falhando, e o erro não informa que uma correção existe. Se uma ferramenta relatar que o formato do Bandcamp mudou, verifique as issues e o CHANGELOG, depois atualize.
• Domínios personalizados. O servidor busca apenas hosts bandcamp.com e *.bandcamp.com, como proteção contra ser direcionado a outros servidores (SSRF). Um lançamento, artista ou gravadora que o Bandcamp lista sob seu próprio domínio (ex.: ilistentojohn.com, visto em uma busca por "carpenter") retorna com slug: null e não pode ser consultado a partir desse resultado, e um artista cujo subdomínio redireciona para seu próprio domínio é reportado como não encontrado, com esse motivo.
• Sem tags para artistas e gravadoras. Suas páginas não contêm nenhuma, então bandcamp_get_artist retorna nenhuma; bandcamp_get_album tem as tags de um lançamento.
• O label de um álbum pode nomear a conta hospedeira. Quando a página não declara gravadora, o campo recorre à conta do Bandcamp que publicou o lançamento. Isso é correto para a página de uma gravadora, e o servidor o suprime quando a conta é um dos artistas creditados — mas em um lançamento autopublicado com crédito de múltiplos artistas cujo nome da conta não compartilha nada com ele (uma banda, um estúdio de jogos, um coletivo), a conta é reportada como a gravadora.
• Catálogos longos são cortados em 100 lançamentos em bandcamp_get_artist.
• Cancelar não interrompe a solicitação. Uma chamada de ferramenta que seu cliente cancela ainda conclui sua solicitação ao Bandcamp em segundo plano (limitada pelo timeout); a v1 não repassa o cancelamento.
• Sem ordenação "recomendados". O Bandcamp personaliza isso apenas para contas de fãs logadas, e este projeto é intencionalmente sem credenciais, então bandcamp_browse_tag oferece top e new.
• Fora do escopo: login, sua coleção ou lista de desejos, compras, dados de vendas e transporte remoto (HTTP/SSE). O servidor roda localmente apenas via stdio.

Princípios

O que este servidor garante e o que ele se recusa a fazer — anônimo e somente leitura, slugs em vez de URLs, nenhum campo que possa carregar um link de stream ou download, um erro honesto quando o Bandcamp muda — está documentado, com o código e os testes que aplicam cada um, em PRINCIPLES.md.

Contribuindo

Veja CONTRIBUTING.md.

Licença

MIT; veja LICENSE.