🎵 Discogs MCP Server

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

✨ 機能

• 🔐 安全な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分ほどで完了します。下の Self-Hosting を参照してください。

🚀 Self-Hosting

一番手っ取り早いのは、上の Deploy to Cloudflare ボタンです。このボタンはリポジトリをGitHubアカウントにクローンし、CloudflareアカウントにKV名前空間と Durable Object を準備し、3つのシークレットの入力を促し、Workers Builds を設定するので、フォークに今後プッシュすると自動的に再デロイされます。

1. Discogsデベロッパーアプリを登録する

discogs.com/settings/developers にアクセスし、Create an Application を選択します。名前は何でも構いません。Callback 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 — Settings → Integrations → Add Integration → 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 / Generic:

{
  "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の共有エグレスIPから出るため、同じ場所からDiscogsにアクセスする他のWorkerも、あなたの60リクエスト/分の枠を消費します。これは、長時間アイドル状態の後の最初のリクエストで、すでに X-Discogs-Ratelimit-Remaining が低いとわかる場合に確認できます。もし問題になるなら、Workerを自分で運用するリレーに向けます。任意の常時稼働マシン（自宅のMac、小さなVPSなど）へのCloudflareリモールと、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時間です。ツール呼び出しとバックグラウンド同期の両方で、1回につき10ミリ秒までです。同期は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 - 詳細は LICENSE ファイルを参照してください。

🙏 謝辞

• Discogs は音楽データベース API を提供してくれることに感謝

• Model Context Protocol は標準プロトコルを提供してくれることに感謝

• Cloudflare Workers はプラットフォームを提供してくれることに感謝