Bandcamp crate digging

bandcamp-mcp

Claude と会話しながら Bandcamp をくまなく調べましょう。レーベルの所属アーティストを調べたり、あるタグの新着作品を確認したり、アルバムの曲目リストや価格を表示したり、コンピレーションの7曲目を実際に作った人を見つけたりできます。bandcamp-mcp はローカルの MCP サーバーです。AI アシスタントがあなたのマシン上のツールを利用するためのもので、Claude Desktop、Claude Code、Cursor、VS Code など、あらゆる MCP クライアントから使用できます。アカウントも API キーも設定も必要ありません。

ステータス：実験的です。 1.0 より前の段階で、現在も活発に開発されています。マイナーバージョンでは動作が変わったり、互換性が損なわれたりする可能性がありますが、パッチバージョンでそうした変更が起きることはありません。サポート対象は最新リリースのみです。

Bandcamp との提携、承認、スポンサー関係はありません。

できること

• 「Sacred Bones のカタログには何があって、それぞれのリリースは誰の作品ですか？」
• 「John Carpenter のアルバム Cathedral を見つけて、曲の長さも含めて曲目を読み上げてください。」
• 「drum-bass タグの新着リリースを10件表示して、それぞれを開いてレーベルとリリース日を教えてください。」
• 「あのコンピレーションは various-artists 名義ですか？各曲を作った人を教えてください。」
• 「このアルバムはいくらですか？価格を自分で決められますか？」
• 「友人から送られてきた Bandcamp のリンクを見つけて、そのアーティストのほかのリリースも教えてください。」

回答は Bandcamp の公開ページから、リアルタイムで取得します。アシスタントがツールを呼び出すたびに、1回リクエストします。サーバーは読み取り専用で、購入やダウンロードを行わず、アカウントにもアクセスしません。ストリーミングリンクやダウンロードリンクがユーザーに届くような項目もありません。

インストール

インストールは npx だけで完了します。MCP クライアントが必要に応じてサーバーを起動し、次回の起動時に修正も取り込みます。

Claude Code：

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

Claude Desktop（Settings → Developer → Edit Config）、またはコマンドから stdio サーバーを起動する MCP クライアントの場合：

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

Cursor： Cursor にインストール、または同じ JSON ブロックを ~/.cursor/mcp.json に追加してください。

VS Code（Copilot エージェントモード）：VS Code にインストール、または code --add-mcp '{"name":"bandcamp","command":"npx","args":["-y","bandcamp-mcp"]}' を実行してください。

Claude Code プラグイン： このリポジトリはプラグイン（.claude-plugin/plugin.json）でもあるため、一覧に登録されると /plugin からインストールできます。

必要条件と実際にテストされている内容

Node.js 20 以降（22 LTS を推奨）を使用してください。Node 18 はサポート終了済みで、MCP SDK の依存関係にも Node 20 が必要です。プッシュのたびに Node 20、22、24 でテストスイートを実行し、パッケージを作成して、空のプロジェクトにインストールしたうえで、それぞれの Node バージョンで Linux、macOS、Windows 上から MCP ハンドシェイクを通じて起動します。保証しているのはこれだけです。他のプラットフォームでも動作する可能性は十分ありますが、テストはしていません。

Bandcamp にはバージョン管理された API がありません。サーバーが読み取るのは bandcamp.com がその時点で配信している内容です。そのため、ライブサイトを対象としたスモークテストを毎日実行しています（上のバッジを参照）。また、ツールが予告なく動作しなくなる可能性があります。詳しくは仕組みと問題が起きる理由をご覧ください。

バージョンを固定するには、bandcamp-mcp@<version> を使用してください（例：npx -y [email protected]）。バージョンを指定しない npx -y bandcamp-mcp は、クライアントが次回起動したときに修正を取り込みます。一方、バージョンを固定したコピーやグローバルインストールしたコピーには修正が反映されません（既知の制限事項を参照）。

Windows

Windows の GUI MCP クライアントでは、.cmd スクリプトであるため、npx を直接起動できないことがよくあります。cmd /c でラップしてください。

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

Claude Code の場合：

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

CI ではこのコマンドをチェックします。windows-latest では、package ジョブがパッケージ化したパッケージをプロジェクトにインストールし、MCP ハンドシェイク（initialize、続いて tools/list）を通じて、そのプロジェクト内で cmd /c npx -y bandcamp-mcp を実行します。このとき、npx はダウンロードせずにインストール済みのコピーを見つけるため、このチェックで確認するのは Windows でのサーバーの起動方法であり、ダウンロードではありません。

トラブルシューティング：「server disconnected」／spawn npx ENOENT

GUI から起動する MCP クライアントは、nvm／volta のシムが含まれない最小限の PATH でサーバーを起動することがよくあります。ターミナルで npx -y bandcamp-mcp が動作する場合でも同様です。パッケージをグローバルにインストールし、クライアントでは絶対パスを指定してください。

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

Windows では、JSON パス内の各バックスラッシュを 2 つにする必要があります。例：C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\bandcamp-mcp\\dist\\index.js。グローバルインストールは自動更新されません。修正を適用するには、npm install -g bandcamp-mcp@latest を実行してください。

ネットワークで npm レジストリへのアクセスがブロックされている場合

クライアントがサーバーを起動するたびに、npx は registry.npmjs.org でパッケージを検索します。レジストリへのアクセスがブロックされている場合や、アクセスできるときとできないときがある場合は、アクセスできる間に npm install -g bandcamp-mcp を一度実行し、上記の絶対パスを使った設定を利用してください。これならレジストリにアクセスせずに起動できます。

仕組みと、問題が起きる理由

Bandcampには公開カタログAPIがないため、ツールを呼び出すたびに、Bandcampのウェブサイト自体が使用するのと同じエンドポイントにライブリクエストを送信します。

• bandcamp_search：Bandcampの検索ボックスで使用されるJSONエンドポイント （/api/bcsearch_public_api/1/autocomplete_elastic）；
• bandcamp_browse_tag：bandcamp.com/discoverで使用されるJSONエンドポイント （/api/discover/1/discover_web）；
• bandcamp_get_albumとbandcamp_get_track：公開されているリリースまたは トラックのページ。主にschema.orgのJSON-LDブロックから読み取り、タグは ページのマークアップから取得します；
• bandcamp_get_artist：アーティストまたはレーベルの/musicページ。 マークアップから読み取ります。

これらはどれも、公開されたバージョン管理付きのAPIではありません。Bandcampはいつでも予告なく変更できるため、その場合、修正がこのプロジェクトからリリースされるまでツールは動作しなくなります。その際、ツールはその旨を表示し（「Bandcampのレスポンス形式が変更されたようです」、またはデータの代わりにボットチェックが返されたことを示します）、イシューのページにリンクします。毎日のスモークテスト（上のバッジ）は、すべてのツールのクライアントコードを実際のBandcampページに対して実行し、失敗があれば追跡用のイシューに報告します。エンドポイントの説明は docs/bandcamp-endpoints.mdにあります。

• メタデータのみです。 リリースはスラッグで識別され、結果の スキーマ（src/client/types.ts）にはストリーミング、ダウンロード、 購入リンク用のフィールドがないため、Bandcampのページにある署名付き 音声リンクをそのまま渡すことはできません。（自由記述のフィールドは アーティスト自身の言葉であり、リンクに言及している場合があります。）
• キャッシュも再公開も行いません。 ツールを呼び出すたびにライブで データを取得します。何も保存せず、結果はMCPクライアントに渡されるだけで、 それ以外の場所には送られません。
• テレメトリーはありません。 このパッケージもVenut Technologiesも 何も収集しません。サーバーが読み取り、送信、保存する内容は PRIVACY.mdに記載されています。 ただし、ツールを呼び出すたびに、お使いのマシンからBandcampへ直接 リクエストが送信されます。Bandcampにはお使いのIPアドレス、問い合わせた 内容、その時刻が伝わります。リクエストには送信元を示す情報も含まれ、 User-Agentは Mozilla/5.0 (compatible; bandcamp-mcp/<version>; +https://github.com/Venut-Technologies/bandcamp-mcp) となるため、ブラウザーからのアクセスには見えません。
• 負荷を抑える設計です。 同時に実行するリクエストは最大3件、各リクエスト間は 最低150 ms、タイムアウトは7秒とし、タイムアウト、トランスポートレベルの 障害（接続のリセットやソケットの切断、DNSまたはTLSエラー）、5xx、 429の場合は1回だけ再試行します（最大5秒のRetry-Afterを尊重します）。 取得するホストはbandcamp.comと*.bandcamp.comのみです。リダイレクトは 手動で追跡し（最大3回）、各転送先がこのリストに含まれていることを確認します。

Bandcampのrobots.txtは、検索エンドポイントを含む/api/へのクローラーのアクセスを禁止し、ブラウズ用エンドポイントは明示的に許可しています。このサーバーはクローラーではありません。ユーザーがツールを呼び出すたびに1ページを取得し、リンクをたどらず、何も保存しません。この解釈と、それに対する反論、そしてBandcampから異議があった場合にツールを変更または削除するという約束は、すべて CONTRIBUTING.mdに記録されています。

リポジトリ（npmパッケージではありません）には、Bandcampから取得したページとAPIレスポンスがテスト用フィクスチャとして含まれています。署名付きストリーミングURLとダウンロードURLは伏せられ、識別情報と自由記述は架空の内容に置き換えられ、各ページはパーサーが読み取るマークアップだけに絞られています。

バグを見つけた場合や、不正利用に関する懸念がある場合は、イシューを作成してください： https://github.com/Venut-Technologies/bandcamp-mcp/issues

セキュリティ上の問題は、代わりに[email protected]へ非公開でお知らせください。詳細は SECURITY.mdを参照してください。

ツール

ツール	入力	戻り値
bandcamp_search	query（1～200 文字）；type：all（デフォルト）、album、artist、track または label	関連度順の一致結果。それぞれ {type, name, artist, slug}。各結果の Bandcamp の is_label フラグで、アーティストとレーベルを区別します。
bandcamp_get_album	slug。例：johncarpentermusic/album/cathedral	タイトル、アーティスト、リリース日、レーベル、タグ、説明、デジタル価格（priceText は最低価格で、priceCurrency と isNameYourPrice も含む）、およびトラックリスト。各トラックには、アーティスト（コンピレーションの場合）、トラック番号、再生時間、slug が含まれます。
bandcamp_get_artist	slug：アーティストまたはレーベルのサブドメイン。例：sacredbonesrecords	名前、所在地、プロフィール、ディスコグラフィー。最大 100 件の {title, slug, type, artist} を返します（レーベルページでは、artist は各リリースのアーティスト）。discographyTotal は全リリース数を示し、discographyTruncated は一部が省略されたかどうかを示します。タグはありません。
bandcamp_get_track	slug。例：johncarpentermusic/track/primeval	アルバム収録曲か単独のシングルかを問わず、任意のトラックページの情報：タイトル、アーティスト、再生時間、タグ、説明、および所属するアルバムを示す album {title, slug}（単独のシングルの場合は、トラック自身のタイトルと slug: null。ページにアルバム名が記載されていない場合は null）。
bandcamp_browse_tag	tag（任意）：ambient、drum-bass、русский-рок などの Bandcamp タグの slug；sort：top（デフォルト）または new；cursor（任意）	ページごとに最大 20 件のリリース。それぞれ {type, name, artist, slug} と、次のページ用の nextCursor を返します。Bandcamp 全体をフィルターなしで一覧表示するには、tag を省略します。自由形式のタグは slug 形式に正規化されます（Drum & Bass → drum-bass）。カーソルは、取得元と同じタグおよび並べ替え条件でのみ使用できます。

すべての slug は、以前の結果から取得した Bandcamp の識別子です （アーティストまたはレーベルの場合は <subdomain>/album/<item>、<subdomain>/track/<item>、またはサブドメインのみ）。表示名ではありません。ツールは URL を受け取りません。Bandcamp の URL https://<subdomain>.bandcamp.com/album/<item> は slug <subdomain>/album/<item> に変換されます。ツールの説明でモデルにそのように伝えます。slug が null の結果は検索できません（カスタムドメインについては下記を参照）。

既知の制限事項

• 単独メンテナーによるベストエフォートのプロジェクトであり、SLA はありません。 毎日のスモークテストは監視を目的としたものであり、サポートを保証するものではありません。
• プロンプトインジェクション。 名前、タイトル、プロフィール、説明、タグは Bandcamp のユーザーが作成するもので、Bandcamp では誰でも公開できます。このサーバーはエンティティをデコードし、マークアップ、制御文字、不可視文字を除去して、長さに上限を設けています。また、各ツールの説明では、モデルに対してこれらを指示ではなくデータとして扱うよう伝えています。これにより、細工されたプロフィールがアシスタントを誘導するリスクは軽減されますが、なくなるわけではありません。
• バージョンを固定したインストールやグローバルインストールは自動修復されません。 Bandcamp 側の変更に対応する修正がリリースされても、自動的に更新されるのはバージョンを固定していない npx のセットアップのみです。@x.y.z に固定したコピーや npm install -g でインストールしたものは動作しないままになり、エラーから修正が存在することもわかりません。ツールから Bandcamp の形式が変更されたと報告された場合は、issues と CHANGELOG を確認してから更新してください。
• カスタムドメイン。 他のサーバーへ誘導されること（SSRF）を防ぐため、このサーバーが取得するのは bandcamp.com と *.bandcamp.com のホストのみです。Bandcamp が独自ドメインで掲載しているリリース、アーティスト、レーベル（例：「carpenter」の検索で見つかる ilistentojohn.com）は slug: null で返され、その検索結果からは参照できません。また、サブドメインが独自ドメインにリダイレクトするアーティストは、理由とともに見つからなかったと報告されます。
• アーティストとレーベルにはタグがありません。 それらのページにはタグがないため、bandcamp_get_artist はタグを返しません。bandcamp_get_album ではリリースのタグが取得できます。
• アルバムの label にホスティングアカウントが表示される場合があります。 ページにレコードレーベルの記載がない場合、このフィールドにはリリースを公開した Bandcamp アカウントが設定されます。レーベル自身のページであれば適切な値であり、アカウント名がクレジットされたアーティストのいずれかと一致する場合、サーバーはこの値を表示しません。しかし、複数のアーティストがクレジットされた自主リリースで、アカウント名がアーティストと何の関係もない場合（バンド、ゲームスタジオ、コレクティブなど）は、アカウントがレーベルとして報告されます。
• bandcamp_get_artist では、リリース数の多いカタログは 100 件で打ち切られます。
• キャンセルしてもリクエストは停止しません。 クライアントがキャンセルしたツール呼び出しでも、Bandcamp へのリクエストはタイムアウトまでバックグラウンドで処理されます。v1 ではキャンセルは伝播されません。
• 「おすすめ」順での並べ替えには対応していません。 Bandcamp のこの順序はログイン済みのファンアカウントに対してのみパーソナライズされます。このプロジェクトでは意図的に認証情報を使用しないため、bandcamp_browse_tag が提供するのは top と new です。
• 対象外： ログイン、コレクションやウィッシュリスト、購入、売上データ、リモート（HTTP/SSE）トランスポート。このサーバーはローカルで stdio 経由のみで動作します。

原則

このサーバーが保証することと、対応しないこと――匿名かつ読み取り専用であること、URL ではなくスラッグを使うこと、ストリーミングリンクやダウンロードリンクを含み得るフィールドを設けないこと、Bandcamp が変更された場合には正直なエラーを返すこと――を、各項目を担保するコードやテストとともに PRINCIPLES.md に記載しています。

貢献

CONTRIBUTING.md をご覧ください。

ライセンス

MIT。詳細は LICENSE をご覧ください。