OP3 MCP Server

---

OP3（Open Podcast Prefix Project）の MCP サーバーです。多くのホスティング API では公開されていないポッドキャスト分析データを AI アシスタントに提供します。ダウンロード数の推移、リスナーの地域、リスナーが利用するアプリ、エピソードごとの内訳を確認できます。

設計上、読み取り専用です。 OP3 は分析サービスです。このサーバーはデータを読み取るだけです。何も変更できないため、エージェントに安心して利用させることができます。

開発の背景。 ほとんどのポッドキャストホストは、API を通じてほとんど情報を公開していません。たとえば Transistor の API が返すのはダウンロード数くらいで、地域情報、アプリのシェア、エピソードごとの直近の推移などはありません。OP3 はリダイレクト時に各ダウンロードを記録するため、これらすべての情報を利用できます。このサーバーは、そのデータをエージェントに提供します。

OP3 とは？

OP3 は、ポッドキャスト向けの無料のオープンな分析用プレフィックスです。エンクロージャー URL の先頭に https://op3.dev/e/ を追加すると、OP3 は実際の音声ファイルにリダイレクトする前に、各ダウンロードを記録します。その後、ダウンロード数、地域、アプリのシェアをレポートします。統計ページは公開されていますが、API の利用にはトークンが必要です。詳細は https://op3.dev をご覧ください。

フィードにまだ OP3 プレフィックスを使用していない場合、そのフィードのデータは OP3 にありません。下記の「OP3 プレフィックスの追加」をご覧ください。

ツール

ツール	返される内容	OP3 エンドポイント
op3_get_show	番組 UUID、タイトル、ポッドキャスト GUID、統計ページ URL、任意のエピソード一覧	GET /shows/{showUuidOrPodcastGuidOrFeedUrlBase64}
op3_show_downloads	月間ダウンロード数、週ごとの内訳、週平均	GET /queries/show-download-counts
op3_episode_downloads	エピソードごとの1／3／7／30日間および全期間のダウンロード数	GET /queries/episode-download-counts
op3_top_apps	過去3暦月のダウンロードシェア上位アプリ／プレーヤー	GET /queries/top-apps-for-show
op3_top_countries	リスナー数上位の国または地域（生データから算出）	GET /downloads/show/{showUuid}
op3_downloads_timeseries	指定期間の生のダウンロードイベント（時刻、国、アプリ、デバイス）	GET /downloads/show/{showUuid}

ほとんどのツールでは番組 UUID が必要です。まず op3_get_show を使って、フィード URL またはポッドキャスト GUID から UUID を取得してください。

一覧を返す各ツールは limit を受け取り、レスポンスが大きくならないよう、デフォルトでは小さい値（10）に設定されています。エージェントはレスポンスごとにトークンを消費します。

セットアップ

1. トークンを取得する

1. https://op3.dev にアクセスして、サインインします。
2. API トークンのページを開き、トークンをコピーします。
3. 試しに使う場合は、OP3 が公開している共有プレビュー用トークン preview07ce を使用できます。公開されている番組に対して利用できます。

2. 番組 UUID を確認する

フィード URL またはポッドキャスト GUID が分かっている場合は、それを指定して op3_get_show を実行するようアシスタントに頼むと、UUID が返されます。番組の OP3 統計ページ URL（https://op3.dev/show/{showUuid}）から UUID を確認することもできます。

3. MCP クライアントを設定する

Claude Code

.mcp.json に追加します：

{
  "mcpServers": {
    "op3": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/op3-mcp"],
      "env": {
        "OP3_API_TOKEN": "your-op3-token"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "op3": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/op3-mcp"],
      "env": {
        "OP3_API_TOKEN": "your-op3-token"
      }
    }
  }
}

4. 確認

アシスタントに、フィード URL を添えて「OP3 で自分の番組を調べて」と尋ね、続けて「先月のダウンロード数はいくつでしたか？」と尋ねます。

OP3 プレフィックスの追加（まだ OP3 を利用していない場合）

ダウンロードが OP3 のプレフィックスを経由して初めて、OP3 にデータが記録されます。利用を開始するには：

1. ポッドキャストホストで、エピソードの音声 URL の先頭に https://op3.dev/e/ を追加します。Transistor、Buzzsprout など、多くのホストではワンクリックで OP3 を有効にできます。ホストの設定で「OP3」または「分析プレフィックス」のオプションを確認してください。
2. 新しいダウンロードの記録が開始されます。プレフィックスを追加する前の過去のダウンロードは、遡って記録されません。
3. https://op3.dev で番組を探し、番組の UUID が含まれる統計ページの URL を控えます。

制限事項

数値の意味を理解するため、以下をお読みください。

• 地域別データは計算されたサンプルであり、正確な合計ではありません。 OP3 には国別の集計エンドポイントがありません。op3_top_countries は生のダウンロード記録を取得し、クライアント側で国別に集計します。結果は代表的な値であり、正確な累計ではありません。OP3 は生の記録を古い順に返すため、明示的な start を指定しない場合、このツールはデフォルトで直近 90 日間（window_days）を対象にします。そうしないと、最近のリスナーではなく、番組の最も古いダウンロードがサンプル対象になってしまいます。この期間内でも記録は古い順にサンプリングされるため、ダウンロード数の多い番組では、max_records のサンプルが期間の開始時点に偏ります。サンプリングされた数を超える記録が期間内にあったかどうかは、レスポンスの sampleHitCap で確認できます。速度とレート制限の余裕を犠牲にして、より大きく代表性の高いサンプルを得るには、max_records を増やしてください（上限は 20000 です）。
• デバイス別の内訳を取得するツールはありません。 OP3 の生の記録には deviceType と deviceName が含まれますが、デバイス別の集計クエリはありません。op3_downloads_timeseries で各記録のデバイス情報を確認できます。アプリ別の割合は op3_top_apps で確認できます。
• 人気アプリのデータは、直近の暦月 3 か月分のみです。 この期間は OP3 によって固定されており、変更できません。
• データはプレフィックスの追加時点から記録されます。 OP3 は、リダイレクトを経由しなかったダウンロードを報告できません。
• OP3 のダウンロードクエリでは、デフォルトでボットが除外されます。 通常はこの設定で問題ありません。
• レート制限は公開されていません。 limit と max_records は控えめに設定してください。HTTP 429 が発生すると、サーバーは明確なエラーを返します。

型付きエラー

API エラーは、src/errors.ts にある型付きエラー階層（OP3APIError 基底クラスと、HTTP ステータスに基づく AuthError、RateLimitError、NotFoundError、ValidationError、ServerError のサブクラス）にマッピングされます。

• AuthError（401/403）— OP3 トークンがないか、無効です。
• RateLimitError（429）— OP3 API へのリクエストが多すぎます。
• NotFoundError（404）— 番組、フィード、またはリソースが存在しないか、まだ OP3 に登録されていません。
• ValidationError（400）— リクエストパラメーターの形式が不正、または無効です。
• ServerError（5xx）— OP3 側でエラーが発生しました。具体的なステータス（500、502、503 など）はメッセージに保持されます。
• OP3APIError — 基底クラスです。マッピングされていないステータスコードやネットワーク障害のフォールバックとして使用されます。

失敗時も、すべてのツール呼び出しは従来と同じ isError: true のレスポンス形式を返します。この型付きエラー階層により、単一の汎用的な「API error」文字列ではなく、発生した問題に応じた具体的なメッセージが表示されます。

開発

git clone https://github.com/conorbronsdon/op3-mcp.git
cd op3-mcp
npm install
npm run build
npm test

ローカルで実行します：

OP3_API_TOKEN=your-token npm start

テストでは fetch をモックしており、ネットワークリクエストは発生しません。

コントリビューション

イシューとプルリクエストを歓迎します。OP3 のエンドポイントのレスポンス形式が変わった場合や、ツールとしてラップする価値のある集計クエリがある場合は、希望する内容と対応する OP3 エンドポイントを説明したイシューを作成してください。読み取り専用の方針を守ってください。このサーバーは分析情報を提供するものであり、何も変更しません。

概要

Conor Bronsdon が構築・保守しています。私は Chain of Thought ポッドキャストを配信しており、AI インフラ、開発者向けツール、そして実際に現場の人々がこれらをどのように活用しているかを取り上げています。この番組を運営するエージェントのワークフローに、リスナーの実態に即した分析データを取り込むために、これを構築しました。

関連ツール：

• podcast-benchmark：公開データに基づいて、同業の番組と比較できます。ここにあるご自身の非公開 OP3 分析データを補完する、公開データのツールです。
• Transistor MCP：Transistor.fm の公式 MCP サーバーです。エピソード、配信、分析に対応しています。
• substack-mcp：Substack の投稿を読み、下書きを管理できます。エージェントのワークフローで安全に使用できます。
• podcastindex-mcp：Podcast Index の MCP サーバーです。人物やトピックでの検索、人気番組の確認、フィードの健全性チェックができます。
• ai-tools-for-creators：アイデアを仕事にしている人向けに、AI スキルと MCP サーバーを厳選してまとめたリストです。

詳細は chainofthought.show および X をご覧ください。

---

免責事項

これは独立した個人プロジェクトであり、いかなる企業とも提携関係になく、スポンサー提供を受けておらず、推奨も受けていません。ここで述べている見解はすべて個人のものです。

ライセンス

MIT