🎵 Discogs MCP Server

AIアシスタントがあなたの個人用Discogs音楽コレクションと対話できるようにする、強力なModel Context Protocol (MCP) サーバーです。公式のCloudflare Agents SDKと**@modelcontextprotocol/sdk**を使用してCloudflare Workers上に構築されています。

✨ 機能

• 🔐 安全なOAuth認証: Discogsアカウントを安全に接続

• 🧠 インテリジェントなムードマッピング: 感情を音楽に変換（「まったり」「エネルギッシュ」「日曜の夜の雰囲気」など）

• 🔍 高度な検索インテリジェンス: ORロジックと関連性スコアリングによるマルチストラテジー検索

• 📊 コレクション分析: 音楽に関する包括的な統計とインサイト

• 🎯 コンテキスト認識型レコメンデーション: ムード、ジャンル、類似性に基づくスマートな提案

• ⚡ エッジコンピューティング: Cloudflare Workersによるグローバルな低遅延応答

• 🗂️ スマートキャッシング: 最適なパフォーマンスのためのKVベースのインテリジェントキャッシュ

• 🔄 バックグラウンドコレクション同期: 6時間ごとのジョブがコレクションのスナップショットをKVに保持し、検索は毎回Discogsをページングする代わりにスナップショットから応答します

Related MCP server: 1001 Albums Generator MCP

⚠️ これは共有サービスではありません

discogs-mcp.comはメンテナーのプライベートインスタンスです。 単一のDiscogsアカウントにロックされており、他のユーザーには403を返します。

なぜか？ Discogs APIのレート制限（1分あたり60リクエスト、送信元IPごとにカウント）は、ユーザー間で共有するには厳しすぎます。1人のユーザーからのアクティブなコレクションクエリだけで飽和する可能性があります。壊れたマルチテナントサービスを実行する代わりに、各ユーザーが独自のDiscogs API資格情報を使用して独自のWorkerをデプロイします。

良いニュース: 独自のコピーをデプロイするのは簡単で、Cloudflare Workersの無料枠で動作し、約10分かかります。以下のセルフホスティングを参照してください。

🚀 セルフホスティング

最速の方法は、上記のDeploy to Cloudflareボタンです。このリポジトリをGitHubアカウントにクローンし、CloudflareアカウントにKV名前空間とDurable Objectをプロビジョニングし、3つのシークレットを入力するよう促し、Workers Buildsを設定して、フォークへの将来のプッシュが自動的に再デプロイされるようにします。

1. Discogs開発者アプリを登録する

discogs.com/settings/developersにアクセスし、アプリケーションを作成します。名前は何でも構いません。コールバックURLは今のところプレースホルダーで構いません（Workerのデプロイ後に戻って設定します）。Consumer KeyとConsumer Secretを保存してください。次に貼り付けます。

2. ボタンをクリックする

プロンプトが表示されたら、以下を貼り付けます:

デプロイが完了すると、CloudflareがWorker URLを表示します — 例: https://discogs-mcp.<your-subdomain>.workers.dev。MCPエンドポイントは/mcpです。

3. DiscogsアプリのコールバックURLを更新する

Discogsアプリに戻り、Callback URLを次のように設定します:

https://discogs-mcp.<your-subdomain>.workers.dev/discogs-callback

4. (任意ですが推奨) インスタンスを自分のDiscogsユーザーにロックする

デフォルトでは、Worker URLを発見した誰でも認証してDiscogsのレート制限予算を消費できます。これを制限するには、フォーク内のwrangler.tomlを編集し、[vars]の下にALLOWED_DISCOGS_USER_IDを設定します:

[vars]
# Single user
ALLOWED_DISCOGS_USER_ID = "123456"

# Or a comma-separated list for multiple users
ALLOWED_DISCOGS_USER_ID = "123456,789012,345678"

数値IDは、https://api.discogs.com/users/<your-username>にアクセスしてidフィールドを確認することで見つけられます。変更をプッシュすると、Workers Buildsが自動的に再デプロイします。

5. MCPクライアントを接続する

以下のhttps://your-worker.workers.devを自分のURLに置き換えてください。

Claude Desktop — 設定 → 統合 → 統合を追加 → https://your-worker.workers.dev/mcp

Claude Code:

claude mcp add --transport http discogs https://your-worker.workers.dev/mcp

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "discogs": {
      "serverUrl": "https://your-worker.workers.dev/mcp"
    }
  }
}

Continue.dev / Zed / 汎用:

{
  "mcpServers": {
    "discogs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-worker.workers.dev/mcp"]
    }
  }
}

MCP Inspector (テスト):

npx @modelcontextprotocol/inspector https://your-worker.workers.dev/mcp

手動デプロイ (代替)

ボタンをスキップしたい場合 — たとえば、完全にローカルなクローンが必要な場合や、ボタンが機能しないCloudflareアカウントを使用している場合:

git clone https://github.com/rianvdm/discogs-mcp.git
cd discogs-mcp
npm install

# Create the two KV namespaces and copy the returned IDs into wrangler.toml
# (replace the empty `id = ""` values under the top-level [[kv_namespaces]] blocks)
wrangler kv namespace create MCP_SESSIONS
wrangler kv namespace create OAUTH_KV

# Set the three secrets
wrangler secret put DISCOGS_CONSUMER_KEY
wrangler secret put DISCOGS_CONSUMER_SECRET
wrangler secret put JWT_SECRET

# Deploy
npm run deploy

その後、上記のステップ3〜5に従ってください（コールバックURL、任意の許可リスト、MCPクライアントの接続）。

任意: Discogs呼び出しを自分のIP経由でルーティングする

Discogsは送信元IPでスロットリングを行い、Workerの送信リクエストはCloudflareの共有egress IPから送信されるため、同じ場所からDiscogsにアクセスする他のWorkerが1分あたり60リクエストの枠を消費します。これは、アイドル状態が数時間続いた後の最初のリクエストで、すでに低いX-Discogs-Ratelimit-Remainingが報告されることで確認できます。問題が発生した場合は、Workerを自分が実行するリレーに向けます: 常時稼働のマシン（自宅のMac、小さなVPSなど）へのCloudflare Tunnelと、https://api.discogs.comに転送し、HostとX-Forwarded-Hostの両方をapi.discogs.comに設定するローカルリバースプロキシ（cloudflared単独ではX-Forwarded-Hostを上書きするためできません）。トンネルホスト名の前に、サービストークンポリシーを持つCloudflare Accessアプリケーションを配置し、次に:

# wrangler.toml: DISCOGS_RELAY_ORIGIN = "https://relay.example.com"
wrangler secret put RELAY_ACCESS_CLIENT_ID
wrangler secret put RELAY_ACCESS_CLIENT_SECRET

DISCOGS_RELAY_ORIGINを空のままにすると、Discogsに直接呼び出します（デフォルト）。リレーに到達できない場合、Workerはそのリクエストに対して直接呼び出しにフォールバックしてログに記録するため、電源がオフのマシンは共有IP動作に劣化し、停止にはなりません。実装と根拠: src/rate-limiter/relay.ts。

コレクションサイズと無料プラン

ここで重要な無料プランの制限はCPU時間です: ツール呼び出しとバックグラウンド同期の両方で、呼び出しあたり10 msです。同期はこれを守るために一度に1ページを保存し、構築するスナップショットは検索に必要なフィールドのみを保持します（リリースあたり約450バイト）。これで約2,000リリースまでのコレクションを快適にカバーできます。それを超えると、検索のたびにスナップショットを読み取ると予算が圧迫され始め、4,000以上のコレクションではsearch_collectionまたはrefresh_collectionがメッセージなしの裸の実行エラーで失敗する可能性があります — これはランタイムが呼び出しを終了しているのであって、Discogsエラーではありません。修正はWorkers Paid（月額$5）で、予算が30秒に引き上げられます。デプロイメントの他の部分は変更されません。

プランに関係なく、get_cache_statsはスナップショットのアイテム数と取得時間、および進行中の同期のページ数を報告するため、キャッシュエントリ数から推測するのではなく、バックグラウンド同期が成功しているかどうかを確認できます。

🔐 認証

このサーバーは、DiscogsをIDプロバイダーとしてMCP OAuth 2.1を使用します。初めて接続するとき:

1. MCPクライアントが自動的にブラウザウィンドウを開きます

2. Discogsでアプリケーションを承認します

3. リダイレクトされて認証されます — コピー＆ペーストは不要です

4. セッションは7日間持続します

🛠️ 利用可能なツール

🔓 公開ツール (認証不要)

🔐 認証済みツール (ログインが必要)

検索と発見

コレクション管理

ウィッシュリスト

フォルダー

カスタムフィールド

診断

📚 MCPリソース

標準化されたMCPリソースURIを介してDiscogsデータにアクセスします:

discogs://collection             # Complete collection (JSON)
discogs://release/{id}           # Specific release details
discogs://search?q={query}       # Search results

💬 MCPプロンプト

🏗️ ローカル開発

# Dev secrets live in .dev.vars (gitignored); the same Discogs app is fine for dev
cp .dev.vars.example .dev.vars   # then fill in DISCOGS_CONSUMER_KEY, DISCOGS_CONSUMER_SECRET, JWT_SECRET

# Run the Worker locally
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8787/mcp

wrangler.toml のデフォルトの [vars] ブロックでは ALLOWED_DISCOGS_USER_ID が空のままなので、ローカル開発はどの Discogs アカウントにも開放されています — テストに便利です。

🧪 テスト

npm test              # vitest in watch mode (runs in workerd via @cloudflare/vitest-pool-workers)
npx vitest run        # one pass, then exit
npm run lint          # ESLint; CI runs lint, test, and a dry-run build

診断

ping と server_info は、Discogs トラフィックがどのように送信されているか（直接、または上記のリレー経由）と、リレーが直接呼び出しにフォールバックしたかどうかを報告します。レートリミッターのライブ状態（残り予算、キューの深さ、サーキットブレーカーのステータス、リレーのフォールバック）については、DEBUG_TOKEN シークレットを設定し、GET /debug/budget?token=<DEBUG_TOKEN> を呼び出してください。シークレットがない場合、エンドポイントは 404 を返します。

🤝 コントリビューション

1. リポジトリをフォークする

2. フィーチャーブランチを作成する（git checkout -b feature/amazing-feature）

3. 変更をコミットする（git commit -m 'Add amazing feature'）

4. ブランチにプッシュする（git push origin feature/amazing-feature）

5. プルリクエストを開く

📄 ライセンス

MIT ライセンス - 詳細は LICENSE ファイルを参照してください。

🙏 謝辞

• 音楽データベース API を提供する Discogs

• 標準規格を提供する Model Context Protocol

• プラットフォームを提供する Cloudflare Workers