musicbrainz-mcp-server

---

概要

MusicBrainz と Cover Art Archive のオープンな音楽メタデータを扱います。アーティスト、リリース、録音、作品、レーベルが対象です。名前で検索したり、MBID、ISRC、ISWC、バーコードで検索したり、ディスコグラフィー全体をページごとに取得したり、カバーアートを取得したりできます。

ツール

ツール	説明
musicbrainz_search_entities	1 種類のエンティティを Lucene 検索し、関連度スコア付きの MBID をランキング順に返します
musicbrainz_get_artist	アーティストのプロフィール：種類、生涯、ディスコグラフィー、関連情報、外部リンク
musicbrainz_get_release_group	リリースグループ（各エディションにまたがるアルバム）：種類、初回リリース日、エディション、カバーアートの有無
musicbrainz_get_release	1 つのエディション：トラックリスト、レーベルとカタログ番号、バーコード、パッケージ
musicbrainz_get_recording	録音（1 回の演奏）：長さ、ISRC、収録されているリリース、演奏者および制作のクレジット
musicbrainz_get_work	作品（楽曲）：種類、ISWC、作詞・作曲者、楽章、編曲、録音
musicbrainz_get_label	レーベル：種類、生涯、レーベルコード、外部リンク
musicbrainz_lookup_identifier	ISRC、ISWC、またはバーコードを録音、作品、リリースに対応付けます
musicbrainz_browse_entities	親 MBID にリンクされたすべてのエンティティをページごとに取得します
musicbrainz_get_cover_art	リリースまたはリリースグループの Cover Art Archive 画像

リソース

リソース	説明
musicbrainz://{entity_type}/{mbid}	エンティティを MusicBrainz の生 JSON 形式で返します。対応する get_* ツールのリンクデータも含まれます

すべてのエンティティは get_* ツールからも取得できるため、ツールのみを使うクライアントでも機能に不足はありません。このリソースにはリストがありません。MBID は musicbrainz_search_entities で検索してください。

機能リファレンス

musicbrainz_search_entities _ツール

• 呼び出しごとに指定できる entityType は1つです（artist、release-group、release、recording、work、label）。フィールドを指定した Lucene query（artist:radiohead AND country:GB など）と、正の整数の limit（デフォルトは25。100を超える値は通知とともに100に制限されます）、ページング用の offset を指定します
• 有効な offset と上流の totalCount を返します。続きの取得には、ページが短い場合も含め、offset + rows returned を使用します。正の合計件数以上の位置でページが空の場合は取得完了を報告します。合計件数より前で予期せずページが空になった場合は、次に進まない offset を提示せず、不一致を報告します
• 各ヒットには、MusicBrainz の順序に従った mbid、name、生の0〜100の score と、artistCredit、isrcs、iswcs、length など、種類固有のフィールドが含まれます。リリース行では status（Official、Bootleg、…）を使用します。アーティスト、リリースグループ、作品、レーベルのサブタイプでは type を使用します。空白文字のみのクエリは blank_query として失敗します

---

musicbrainz_get_artist _ツール

• mbid と、重いサブリソースを除外するための inc_release_groups および inc_relationships（どちらもデフォルトは true）
• 種類、性別、国、地域、lifeSpan、別名、タグに加え、releaseGroups（1ページ）、relationships（バンドへの参加、コラボレーション）、externalLinks（Wikidata、Discogs、公式サイト）を返します

---

musicbrainz_get_release_group _ツール

• mbid のみを指定します。primaryType、secondaryTypes、firstReleaseDate、artistCreditString を含む artistCredit、タグ、1ページ分の releases（エディション）を返します
• coverArt（exists、count、front、back）は、Cover Art Archive へのライブ確認の結果です。確認に失敗した場合、このフィールドは通知とともに省略され、「アートなし」と報告されることはありません

---

musicbrainz_get_release _ツール

• mbid、media_offset（デフォルトは0）、media_limit（デフォルトは20、上限なし）を指定します。順序付けされた media と、各メディアの全トラック（position、title、m:ss形式の length、recordingId）、labelInfo（レーベルと catalogNumber）、barcode、status、date、country、packaging、language／script、releaseGroupId を返します
• mediaTotal と trackTotal は、正規化されたすべてのメディアとトラックの出現数を数えます。上流のメディアごとの trackCount は保持されます。mediaOffset は取得範囲を示します。メディアが残っている場合は、truncated、shown、cap と通知で次の media_offset を示します。末尾の空ページでは取得完了を報告します。release リソースには完全な生のトラックリストが保持されます
• coverArt はリリースレコードに含まれる利用可能性の概要です。画像 URL を取得するには musicbrainz_get_cover_art を呼び出してください

---

musicbrainz_get_recording _ツール

• mbid と、演奏者、プロデューサー、エンジニアのクレジット、作品へのリンク、外部リンクを取得するための inc_relationships（デフォルトは true）
• length、isrcs、artistCredit、firstReleaseDate、上流の1ページ分の releases（最大25件）、relationships、externalLinks を返します
• releaseAppearanceSummary には shown、cap: 25、completeness が含まれます。ページが存在し、25件未満の場合は complete、正確な件数がわからないままページが満杯、またはページが存在しない場合は unknown、上流の正確な件数が返されたページ数を超える場合は truncated となります。件数が不明な場合、totalCount は省略され、件数を取得するリクエストは追加されません。出現を列挙するには、埋め込みの順序と参照順序が異なる場合があるため、musicbrainz_browse_entities（target_type=release、link.recording=<mbid>、offset=0）を使用してください

---

musicbrainz_get_work _tool

• ライター、作曲家、作詞家のクレジット、楽章と編曲、その作品を演奏した録音、外部リンクを取得するには、mbid と inc_relationships（デフォルトは true）を指定します
• type、languages、iswcs、別名、タグを返します。録音との関連は最初の25件のみ保持されます（その他の関連とリンクはすべて保持されます）。全件数は totalCount で示され、一部が省略された場合は truncated、shown、cap が表示されます
• 作品の全録音を列挙するには、work で recording をブラウズし、録音ごとの関連属性と日付を取得するために musicbrainz_get_recording を呼び出します
• targetType: "work" を持つ relationships エントリーをたどるには、その targetId を別の musicbrainz_get_work 呼び出しで使用します。direction は親子リンクを区別します。任意の orderingKey は、上流のシーケンスキー（ゼロを含む）を保持し、targetDisambiguation は編曲を区別します。関連は上流の配列順を保持しますが、楽章の順序とは一致しない場合があります

---

musicbrainz_get_label _tool

• mbid のみを指定します。タイプ、国、地域、lifeSpan、labelCode（接頭辞を除いた LC 番号）、別名、タグ、externalLinks を返します
• リリースは埋め込まれません。musicbrainz_browse_entities（target_type=release、link.label）で列挙してください

---

musicbrainz_lookup_identifier _tool

• id_type が isrc の場合は録音、iswc の場合は作品、barcode の場合はリリースを検索します。バーコードは UPC/EAN の数字で、スコア順に最大25件の候補を返します。各候補には score が含まれます
• ISRC は GBAYE9701274 のような区切りのない形式、または GB-AYE-97-01274 のような印字形式を受け付けます。大文字と小文字、および前後の空白は無視されます。ISWC は T-010.140.236-1 または T0101402361 を受け付け、任意のグループ区切り記号を使用できます。空白と大文字・小文字は無視されます。結果には、正規化された区切りなしの ISRC、または T-DDD.DDD.DDD-C 形式の ISWC が返されます。不正なコードはリクエスト前にエラーになります
• result.kind（recordings | works | releases）は、返された結果の種類を示します。失敗時は invalid_identifier または identifier_not_found になります

---

musicbrainz_browse_entities _tool

• target_type と、link 内の親 MBID をちょうど1つ指定します。releaseGroup／release_group は release-group の別名です。正の整数である limit のデフォルトは25です。100を超える値は100に制限され、その旨が通知されます。検索とブラウズの両方で最大100を適用するには、MUSICBRAINZ_CLAMP_OVERSIZED_LIMITS=off を設定します
• 上流の totalCount を報告します。残りがある場合は truncated が設定され、空でないページには実際に返された行数に基づく次の offset が示されます。空のページでは、リンクされたエンティティがゼロ件である場合、結果をすべて取得済みの場合、または総数に達する前に予期せず空のページが返された場合を区別します。上限とページングに関する案内は、同じ通知にまとめられます。リリースの行では status を使用し、その他のエンティティでは type を使用します
• link が欠落している、余分なリンクがある、または形式が不正な場合は invalid_link、親が不明な場合は entity_not_found になります。エディションのトラックを順番どおりに取得するには、musicbrainz_get_release を使用してください

ターゲット	受け付ける親キー
artist	area、recording、release、release-group、work
label	area、release
release-group	artist、release
release	area、artist、label、recording、release-group
recording	artist、release、work
work	artist

---

musicbrainz_get_cover_art _ツール

• mbid と entity_type：release（デフォルト）または release-group。後者は representativeRelease に解決されます。limit のデフォルトは 25 で、100 を超える値は 100 に制限されます。offset のデフォルトは 0 です。これらのウィンドウはアーカイブインデックスがキャッシュされた後に適用され、検索／ブラウズの上限設定とは独立しています
• images はアーカイブ内の順序を維持し、front／back、types、imageUrl、250／500／1200px のサムネイルを含みます。totalCount は正確な件数で、offset はウィンドウを示し、hasArt は最終ページが空の場合でもアーカイブ全体を対象とします。上限、続き、末尾到達、またはアートなしに関する案内は、1つの通知にまとめられます。画像がさらに残っている場合は、truncated、shown、cap が表示されます
• 不明な MBID は entity_not_found エラーになります。MusicBrainz が MBID の存在を確認できない場合は、その旨を示す通知とともに空の結果が返されます

---

musicbrainz://{entity_type}/{mbid} _リソース

• entity_type は artist、release-group、release、recording、work、または label です。MusicBrainz の生レコードを application/json として返します
• 対応する get_* ツールと同じデフォルトの関連データを取得します。失敗時のエラーは invalid_mbid と entity_not_found です
• Work の JSON には、生の作品間リレーションシップが含まれ、最初の 25 件の録音リレーションシップが保持されます。recordingRelationshipSummary は録音の正確な件数と、件数が打ち切られているかどうかを示します
• Recording の JSON には、キャッシュ済みの生データを変更せずに、録音ツールと同じ releaseAppearanceSummary が含まれます。Release の JSON にはすべてのメディアとトラックが保持されます。ツールのメディアウィンドウはリソースには適用されません

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを提供します。

MusicBrainz 固有の機能：

• MusicBrainz Web Service v2 および Cover Art Archive 用のキー不要のクライアントです。すべてのリクエストには、MusicBrainz が要求する説明的な User-Agent musicbrainz-mcp-server/<version> ( <contact> ) が付与されます。連絡先には MUSICBRAINZ_CONTACT が使われます
• エンティティは MBID（ハイフン区切りの UUID）で指定します。大文字と前後の空白は正規化されます。不正な形式またはすべてゼロの ID は invalid_mbid（ブラウズの場合は invalid_link）となり、形式が正しくても不明な ID は entity_not_found になります
• インスタンス内のすべてのクライアントを対象に、MusicBrainz への呼び出しは約 1 リクエスト／秒に制限されるため、長時間のブラウズには時間がかかります
• 1回のリクエストでディスコグラフィー、リレーションシップ、トラックリスト、外部リンクをまとめて取得します。レスポンスはデフォルトで 24 時間キャッシュされ、一時的な上流エラーはバックオフ付きで再試行されます

エージェントに適した出力：

• Artist のリリースグループ、リリースグループのエディション、Recording のリリースへの収録情報は、1ページ分（25件）を埋め込みます。ブラウズでは全件が列挙されます。Recording の収録情報は、件数を取得するリクエストなしで完全性を示します。Work の録音リレーションシップは 25 件を上限とし、正確な件数が報告されます。Label にはリリースが埋め込まれません
• 検索結果には有効なクエリが含まれ、検索とブラウズでは上流の正確な合計件数が報告されます。合計件数が欠落または無効な場合、件数を作り出すのではなく、不正な上流レスポンスとしてエラーになります
• 判別可能な出力：musicbrainz_lookup_identifier は kind タグ付きのユニオン型を返すため、呼び出し側は文字列解析ではなくデータに基づいて分岐できます
• 導出した信頼度ではなく、上流の生の関連度 score を使用します。上流にないフィールドは、作り出さずに省略されます

はじめに

公開ホストインスタンス

公開インスタンスは https://musicbrainz.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を介して、任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "streamable-http",
      "url": "https://musicbrainz.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/musicbrainz-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MUSICBRAINZ_CONTACT": "[email protected]"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/musicbrainz-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "MUSICBRAINZ_CONTACT": "[email protected]"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "musicbrainz-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "[email protected]",
        "ghcr.io/cyanheads/musicbrainz-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 [email protected] bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以上）。
• API キーやアカウントは不要です。サーバーにはデフォルトの連絡先が設定されていますが、共有環境またはホスト環境にデプロイする場合は、MUSICBRAINZ_CONTACT にご自身のメールアドレスまたは URL を設定してください。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/musicbrainz-mcp-server.git

2. ディレクトリに移動します：

cd musicbrainz-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set MUSICBRAINZ_CONTACT (optional but recommended)

設定

変数	説明	デフォルト
MUSICBRAINZ_CONTACT	User-Agent に含めて送信するメールアドレスまたは URL です。共有インスタンスまたはホストインスタンスでは、ご自身のものを設定してください。	リポジトリ URL
MUSICBRAINZ_BASE_URL	MusicBrainz Web Service v2 のベース URL（例：プライベートミラー）。	https://musicbrainz.org/ws/2
MUSICBRAINZ_RATE_LIMIT_RPS	クライアント側のリクエスト毎秒数の上限（0.1～50）。	1
MUSICBRAINZ_CACHE_TTL	レスポンスキャッシュの TTL（秒）。0 にするとキャッシュが無効になります。	86400
MUSICBRAINZ_TIMEOUT_MS	リクエストごとの HTTP タイムアウト（ミリ秒）。	30000
MUSICBRAINZ_MAX_RETRIES	上流側で一時的な障害が発生した場合の再試行回数。	3
MUSICBRAINZ_CLAMP_OVERSIZED_LIMITS	検索／ブラウズの上限が 100 を超えた場合に、通知を表示して 100 に制限します。off にすると、上限 100 のスキーマ検証が復元されます。厳密なブール値（true／false、on／off、1／0、yes／no）。	true
COVER_ART_BASE_URL	Cover Art Archive のベース URL。	https://coverartarchive.org
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
OTEL_ENABLED	OpenTelemetry を有効にします。	false

省略可能なオーバーライドの一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security, packaging
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against the linter rules
  

Docker

docker build -t musicbrainz-mcp-server .
docker run --rm -e [email protected] -p 3010:3010 musicbrainz-mcp-server

Dockerfile は、デフォルトで HTTP トランスポート、ステートレスセッションモードを使用し、ログを /var/log/musicbrainz-mcp-server に出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイント。ツールとリソースを登録し、両方のサービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/services/musicbrainz	MusicBrainz WS/2 クライアント。User-Agent、レートリミッター、レスポンスキャッシュ、再試行、ドメイン型を扱います。
src/services/cover-art	Cover Art Archive クライアント。404 を空の画像セットにマッピングし、リリースグループのリダイレクトに追従します。
src/mcp-server/tools	ツール定義（*.tool.ts）。検索、参照、ブラウズ、カバーアートに対応する 10 個の読み取り専用ツールです。
src/mcp-server/resources	リソース定義。エンティティミラー musicbrainz://{entity_type}/{mbid}。
tests/	src/ に対応する単体テストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md/AGENTS.md を参照してください。要点は次のとおりです：

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch を使用しないでください
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用してください
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレル経由で登録してください
• 上流へのすべての呼び出しはサービス経由で行い、直接 fetch() を呼び出さないでください。これにより、User-Agent、レートリミッター、キャッシュが適用されます
• 外部 API のデータはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマを返してください。不足しているフィールドを決して捏造しないでください

貢献

Issue を歓迎します。提出前にチェックとテストを実行してください：

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細はLICENSEをご覧ください。

MusicBrainz のコアエンティティデータはCC0です。サーバーが読み取るのはこのコアメタデータのみで、異なるライセンスが適用される注釈テキストは取得しません。カバーアートは、MusicBrainz と Internet Archive の共同プロジェクトであるCover Art Archiveから取得します。画像 URL はリンクするだけで、画像を再ホストすることはありません。また、各画像の著作権はそれぞれの権利者に帰属します。派生物の利用時には、MusicBrainz と Cover Art Archive を出典として明記してください。