🎵 Discogs MCP Server

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

✨ 特徴

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

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

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

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

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

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

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

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

Related MCP server: navigravity

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

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.<あなたのサブドメイン>.workers.dev。MCP エンドポイントは /mcp です。

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

Discogs アプリ設定 に戻り、コールバック 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/<あなたのユーザー名> にアクセスし、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 を自身が運用するリレーに向けます：Cloudflare Tunnel から任意の常時稼働マシン（自宅の Mac、小規模な VPS）への接続で、ローカルリバースプロキシが 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 を参照してください。

🔐 認証

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

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

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

3. リダイレクトされ、認証完了 — コピーペーストは不要です

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

🛠️ 利用可能なツール

🔓 公開ツール（認証不要）

🔐 認証済みツール（ログインが必要）

検索と発見

コレクション管理

Wantlist

フォルダ

カスタムフィールド

診断

📚 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 '素晴らしい機能を追加')

4. ブランチにプッシュ (git push origin feature/amazing-feature)

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

📄 ライセンス

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

🙏 謝辞

• Discogs（音楽データベースAPI用）

• Model Context Protocol（標準プロトコル用）

• Cloudflare Workers（プラットフォーム用）