Apple Podcasts MCP Server

---

番組の所有者が Apple で確認できる分析データを取得する MCP サーバーです。エピソードの再生数、リスナーがどこまで聴いたか、フォロワー数が増減しているかを確認できます。これらのデータは Apple Podcasts Connect と Reporter サービスの裏側にあり、Apple の公開カタログ API には含まれていません。

Apple の実アカウントを使った検証は一切行っていません。 プロトコルは Apple の Reporter ドキュメントに基づいて実装し、手作業で作成したフィクスチャを使ってテストしています。このサーバーが送信するリクエストも、解析するレスポンスも、実際の通信で確認できていません。実際に利用して返ってきた内容を報告する Issue をいただけると、大いに役立ちます。

このサーバーを使うには、Apple Podcasters Program への加入が必要です。 Reporter は ベンダー番号 でユーザーを識別します。ベンダー番号は、Program 登録によって作成されるベンダー契約の一環として発行されます。一般的な無料の Podcasts Connect アカウントにはベンダー番号がありません。そのアカウントの「Account → Details」ページに表示されるのはアカウント UUID で、別の識別子のため、このサーバーでは使えません。登録には年会費がかかり、税務情報と銀行情報を含む法人情報が必要です。Apple Podcasts の機能の提供状況をご覧ください。

登録していない場合、設定できることはなく、このサーバーもお役に立てません。代わりに、Podcasts Connect の「Analytics」セクションで数値をご確認ください。

読み取り専用です。 Reporter は読み取りのみを行います。このサーバーで番組、エピソード、アカウントが変更されることはありません。

このサーバーでできないこと

これは iTunes Search／公開カタログ API ではありません。番組名での検索、公開チャートの閲覧、アートワークの取得、レビューや評価の取得はできません。私が確認したほかの「Apple Podcasts」MCP サーバーは、認証情報不要の公開カタログを利用しています。このサーバーではベンダー番号とアクセストークンが必要ですが、その代わりにご自身の再生データを取得できます。

また、以下には対応していません。

• サブスクリプションと収益。 Reporter には apSubscriptionsSales などがありますが、このサーバーでは対応していません。
• Podcasts Connect アカウントを作成する前のデータ。 Reporter がレポートするのは、Apple がご自身のベンダー番号について記録したデータです。
• 当日分のデータ。 Apple のデータ公開には1～2日の遅れがあるため、期間の終了日はデフォルトで2日前になります。
• ダウンロード数。 Apple がレポートするのは再生数とリスナー数で、ダウンロード数ではありません。ダウンロード数を確認したい場合は、op3-mcp などのホスティングサービスまたはプレフィックス分析データをご利用ください。

ツール

ツール	返される内容
apple_podcasts_check_access	トークンが機能するか、読み取り可能なベンダー番号、および Apple から返された場合のトークンの有効期限。リスニングデータは含まれません。
apple_podcasts_summary	指定した期間における番組単位の再生数、ユニークなリスナー数、エンゲージしたリスナー数、フォロワー数を、期間ごとおよび合計で表示します。リスナー数は人数ではなくデバイス数です。指標の意味を参照してください。
apple_podcasts_episodes	指定した期間におけるエピソードごとの再生数とリスナー数を、期間を通じて集計し、ランキング順に表示します。
apple_podcasts_followers	指定した期間の各期間におけるフォロワー数と、期間内の変化を返します。

意図的に「生レポートを取得する」ツールは用意していません。Reporter は日付ごとに 1 つのレポートを返し、各レポートにはエピソードごとの行が含まれます。また、全世界以外のバリエーションでは、エピソードごとにストアフロント単位の行も含まれます。これを 1 か月分取得すると数万行になるため、そのままエージェントに渡すと、タブ区切りテキストでコンテキストウィンドウを消費してしまいます。

各ツールでは、日付範囲と上限を明示的に指定します。

• max_periods は、1 回のツール呼び出しで実行する Reporter 呼び出しの回数を制限します。上限は 31 です。Reporter には範囲クエリがなく、日付ごとに HTTP の往復が 1 回必要です。そのため、これは形式的な制限ではなく、レート制限を守るためのものです。指定範囲が上限を超える場合、直近の期間だけが対象になり、レスポンスに rangeTruncated でその旨が示されます。
• apple_podcasts_episodes の limit は、返される行数を 50 件までに制限します。
• 範囲のデフォルトは短めです。Daily は 7 日間、Weekly は 7 週間、Monthly は 6 か月です。各デフォルト範囲は、デフォルトの max_periods である 7 に収まるよう設定されているため、日付を指定せずに呼び出すと、途中で切り詰められずに期間全体のデータが返されます。

指標の意味

Apple の数値は人数ではありません。Podcasts Connect Analytics は「ユニークデバイスからのリスニングと視聴の完了率」を集計します（Apple）。つまり、リスナー数はデバイス数です。スマートフォンと CarPlay 対応のヘッドユニットを持つ人は、2 人として数えられる場合があります。

• 再生数 — 誰かがエピソードの再生を開始した回数です。
• ユニークなリスナー数 — 1 秒を超えて再生したデバイス数です。
• エンゲージしたリスナー数 — エピソードを20 分以上または 40％以上再生したデバイス数です。これが Apple の定める視聴の深さの基準です。完了率ではなく、エピソードの 40％を再生しても最後まで聴いたことにはなりません。
• フォロワー数 — 増減数ではなく、その時点での数です。この項目に注意が必要な理由については、列名についてを参照してください。

セットアップ

1. ベンダー番号とアクセストークンを取得する

どちらもApple PodcastsのReporter側で取得できます。Reporterの利用にはApple Podcasters Programへの登録が必要です。冒頭の注記をご覧ください。無料のPodcasts Connectアカウントでは、どちらも取得できません。

登録済みのアカウントは、Reporter User Guideに記載されているAppleのReporterツールを通じて、ベンダー番号とアクセストークンを取得できます。ReporterのgenerateTokenコマンドでアクセストークンを発行し、viewTokenコマンドで現在のトークンと有効期限を確認できます。

Appleのドキュメントに記載されている、注意すべき制約が2つあります。

• Apple Accountごとに有効なトークンは1つです。 新しいトークンを生成すると、以前のトークンはただちに無効になります。このアカウントでReporterを使っているもの（別のツール、同僚、昨年設定したダッシュボードなど）がある場合、ここでトークンを生成すると、それらは通知なく使えなくなります。また、その失敗はトークンの期限切れとまったく同じように見えます。
• トークン管理は自動化を想定していません。 Appleによると、これらのコマンドは「自動利用を想定しておらず、アクセスがレート制限される場合があります」。そのため、トークンのローテーションをスクリプト化しないでください。

このセクションで以前案内していたSettingsページは存在しません。 以前の手順では、Podcasts Connect → Settingsでベンダー番号を確認し、アクセストークンを生成するよう案内していました。Podcasts ConnectにSettingsページはありません。AccountセクションにはPeople、API Keys、Detailsがありますが、いずれにもベンダー番号はありません。この手順はAppleのドキュメントを基に作成されており、実際の製品で確認されていませんでした。

そこでのAPI Keysページは別の機能であり、代わりにはなりません。Appleによると、APIキーを使うと「ホスティングプロバイダーは、あなたに代わって番組やエピソードをApple Podcastsに公開できますが、リスニング分析データにはアクセスできません」。APIキーを生成しても、このサーバーには何も許可されません。また、キーの作成後にサービスを追加するよう変更することもできません。

2. ビルドする

npmで公開されています。以下の設定ブロックではnpxを使用しており、初回実行時に取得されるため、クローンは不要です。

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

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

Claude Code

.mcp.jsonに追加します。

{
  "mcpServers": {
    "apple-podcasts": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/apple-podcasts-mcp"],
      "env": {
        "APPLE_PODCASTS_ACCESS_TOKEN": "your-access-token",
        "APPLE_PODCASTS_VENDOR_ID": "87654321"
      }
    }
  }
}

Codex CLI

~/.codex/config.tomlに追加します。

[mcp_servers.apple-podcasts]
command = "npx"
args = ["-y", "@conorbronsdon/apple-podcasts-mcp"]
env = { APPLE_PODCASTS_ACCESS_TOKEN = "your-access-token", APPLE_PODCASTS_VENDOR_ID = "87654321" }

Claude Desktop

Claude Codeと同じブロックをclaude_desktop_config.jsonに追加します。

サーバーは認証情報がなくても起動するため、クライアントはツールの一覧を取得できます。その後、各ツールを呼び出すと、不足している変数を知らせるメッセージとともに失敗します。

トークンで複数のアカウントを読み取れる場合

APPLE_PODCASTS_ACCOUNT_IDは任意で、ほとんどの構成では不要です。Reporterがコード214「このトークンは複数のアカウントにアクセスできます。アカウント番号を指定してください」と応答する場合に設定してください。Reporterがアカウントを選ぶことはないため、アカウント番号を指定するまで、すべての呼び出しが失敗します。

"env": {
  "APPLE_PODCASTS_ACCESS_TOKEN": "your-access-token",
  "APPLE_PODCASTS_VENDOR_ID": "87654321",
  "APPLE_PODCASTS_ACCOUNT_ID": "2011425"
}

これはツールの引数ではなく、環境変数です。認証情報の一部であり、質問の一部ではないためです。呼び出しごとに変わることはなく、ほとんどの人が設定しない引数のために、すべてのツールのスキーマでコンテキストを消費する必要はありません。アカウントが1つだけの場合は設定しないでください。Reporterは空のアカウント欄を拒否するため、サーバーは空欄を送信せず、その項目自体を省略します。apple_podcasts_check_accessを実行すると、使用中のアカウント番号が返されます。

3. 確認する

アシスタントに**「Apple Podcastsへのアクセスを確認してください」**と尋ねます。これによりapple_podcasts_check_accessが実行され、トークンが機能していることと、ベンダー番号がトークンで読み取れるものかどうかを確認できます。この2つの失敗は、外部から見ると同じように見えます。

180 日ごとのトークンローテーション

Apple Reporter のアクセストークンは、生成から 180 日後に有効期限が切れます。 セットアップを壊す原因となるのはこれです。しかも、気づかないうちに壊れます。サーバーは起動し続け、ツールも一覧に表示されますが、すべての呼び出しが失敗し始めます。

トークンの有効期限が切れると、ツールは次を返します。

Apple Reporter error (123) on Sales.getReport: Access token is expired. Reporter tokens
last 180 days. Generate a new one in Apple Podcasts Connect > Settings > Access Token and
update APPLE_PODCASTS_ACCESS_TOKEN.

ローテーションするには：

1. Reporter User Guideに従って、Reporter の generateToken で新しいトークンを発行します。
2. 新しいトークンが作成された時点で古いトークンは使えなくなるため、設定を同じタイミングで更新できるときに作業してください。
3. APPLE_PODCASTS_ACCESS_TOKEN を設定した箇所すべてで値を置き換え、新しい環境変数を読み込ませるために MCP クライアントを再起動します。

ローテーションはアプリケーションごとではなく、アカウント全体に適用されます。 Apple Account ごとに有効なトークンは 1 つだけです。アカウント上で Reporter と通信するほかのものは、この操作でトークンをローテーションした時点から、このサーバーが報告するのと同じコード 123 で失敗し始めます。Reporter へのアクセスが必要なものが複数ある場合は、同じトークンを共有し、一緒にローテーションする必要があります。

セットアップ時に行っておくとよいことが 2 つあります。

• apple_podcasts_check_access を実行し、Apple から tokenExpires の日付が返された場合は記録してください。すべてのアカウントで Sales.viewToken から有効期限が返されるわけではありません。返されない場合は応答にその旨が示されるため、自分で日付を管理してください。
• 170 日目にカレンダーのリマインダーを設定してください。ローテーションは 30 秒で済みますが、分析の途中で有効期限が切れたことに気づくのは避けたいものです。

有効期限切れ（コード 123）とトークンの拒否（コード 124）は、ここでは別々のエラータイプです。対処方法が異なり、前者はローテーションが必要で、後者はトークンの貼り付け方が間違っていることを意味します。

実例

あなた： Apple で先週の番組の成績はどうでしたか。また、どのエピソードが成績を支えましたか？

アシスタントは 2 つの呼び出しを実行します。

apple_podcasts_summary を period: "Daily"、start: "2026-07-24"、end: "2026-07-30" で呼び出します。

{
  "reportType": "apShowListeningWorldwide",
  "period": "Daily",
  "requestedRange": { "start": "20260724", "end": "20260730" },
  "periodsReturned": 7,
  "totals": { "plays": 8940, "uniqueListeners": 5620, "engagedListeners": 3810 },
  "totalsNote": "Totals sum the flow metrics (plays, listeners, time listened) across periods. Followers is a level, not a flow, so it is reported per period in the series and is deliberately absent from totals.",
  "series": [
    { "date": "20260724", "rows": 1, "metrics": { "plays": 1204, "followers": 9430 } },
    { "date": "20260725", "rows": 1, "metrics": { "plays": 1530, "followers": 9512 } }
  ],
  "resolvedColumns": { "plays": "Plays", "followers": "Followers" }
}

続いて、同じ期間で apple_podcasts_episodes を sort_by: "engagedListeners"、limit: 5 で呼び出します。

{
  "totalEpisodes": 43,
  "returned": 5,
  "sortedBy": "engagedListeners",
  "episodes": [
    { "episodeId": "1000712346", "episodeName": "What evals actually measure",
      "plays": 830, "uniqueListeners": 635, "engagedListeners": 530 }
  ]
}

注目すべきなのは engagedListeners です。再生数は再生開始回数を数えますが、エンゲージリスナー数はエピソードを 20 分以上、または 40％以上聴いたデバイスの数を数えます。再生数では上位でもエンゲージメントでは下位のエピソードは、クリックされたものの、聴かれてはいません。

（上記の値は説明用です。列名はアカウントのレポートに基づきます。次のセクションをご覧ください。）

列名について

Apple はポッドキャストのリスニングレポートの列構成を公開しておらず、レポートのバージョン間で列名を変更したこともあります。そのため、このサーバーでは列名をハードコードしていません。各指標はエイリアステーブル（src/tsv.ts）を通じて解決され、すべての応答で次の内容が報告されます。

• resolvedColumns — 各指標に対してレポート内で実際に一致した列。
• unmappedColumns — 既知のどの列にも一致しなかった、レポート内の列。

Apple が列名を変更した場合、apple_podcasts_summary と apple_podcasts_episodes は、何も知らせずにゼロを返すのではなく、一致しなかった列名とともに schemaNote を返します。関心のある指標が unmappedColumns に含まれていたら、列名を添えてイシューを作成してください。エイリアステーブルに追加されます。

フォロワー数にも同じ注意が必要です。Apple のフォロワー列は、累計値として扱われる場合と、期間ごとの件数として扱われる場合がありました。apple_podcasts_followers は resolvedColumn、change（最新値から最初の値を引いたもの）、sumAcrossPeriods を返し、推測で代行するのではなく、それぞれのケースでどちらを参照すべきかを示します。

エラー

Reporter は REST ではありません。ほとんどの失敗では、HTTP 200 が返されることも多いものの、本文に数値コードを含めて応答します。そのため、ステータスコードを信頼するクライアントは、エラーエンベロープをレポートとして解析してしまいます。このサーバーは本文を確認します。コードは型付きエラーに対応しています（src/errors.ts）。

エラー	Reporter コード	意味
TokenExpiredError	123	180 日の有効期間が終了しました。トークンを更新してください。
TokenInvalidError	124, 125, 132, HTTP 401/403	トークンが存在しない、形式が不正、または拒否されました。
VendorError	200, 300	このトークンでは読み取れないベンダー番号です。apple_podcasts_check_access を実行してください。
AccountError	214, 215	トークンが複数の Apple アカウントにアクセスでき、Reporter が選択できないか、指定されたアカウント番号が間違っています。APPLE_PODCASTS_ACCOUNT_ID を設定してください。
NoDataError	209, 211, 213	リクエストは有効ですが、その期間のレポートがありません。これはよくあることです。レポートの公開は遅れることがあり、データの少ない期間には何も生成されません。
RateLimitError	117, HTTP 429/503	Apple がリクエストを制限しているか、レポートが遅延しています。期間を短くしてください。
BadRequestError	201–208	レポートの種類、日付の種類、またはそれらの組み合わせが不正です。
ReporterError	その他すべて	基底クラスです。ネットワーク障害にも使用されます。

範囲の途中で NoDataError が発生した場合、エラーとして送出するのではなく処理されます。日付は missingPeriods に記録され、残りの範囲の処理は続行されます。範囲全体でデータがまったく返されなかった場合は、ゼロの一覧ではなく、その理由が説明されます。

Reporter の日付がまったく生成されない範囲は、別の応答になります。週次レポートの日付は週の最終日である日曜日になるため、月曜日から金曜日までの週次範囲にはレポートの日付が含まれず、Apple には何も送信されません。送信されていないリクエストについて、Apple の公開遅延のせいにするのではなく、その旨を応答で伝えます。

プロトコルに関する注意事項

Reporter は、トークンと角括弧付きのコマンドを含む JSON ドキュメントを格納した、単一のフォームエンコードフィールド jsonRequest を含む HTTP POST を受け付けます。

POST https://reportingitc-reporter.apple.com/reportservice/sales/v1
Content-Type: application/x-www-form-urlencoded

jsonRequest={"accesstoken":"...","version":"2.2","mode":"Robot.XML",
             "queryInput":"[p=Reporter.properties, Sales.getReport, 87654321,apShowListeningWorldwide,Summary,Daily,20260728]"}

バージョン 2.2 は重要です。トークンベースの認証（generateToken）には Reporter 2.2 以降が必要で、古いバージョン文字列ではトークンが拒否されます。成功したレポートは、タブ区切りのテキストとして gzip 圧縮されて返されます（Content-Type: application/a-gzip）。ヘッダー行は 1 行で、引用符は使われません。

APPLE_PODCASTS_ACCOUNT_ID が設定されている場合、account フィールドが同じ JSON ドキュメントに追加されます。未設定の場合は省略されます。Reporter は空の account を「指定なし」ではなくエラーとして扱うためです。

Apple のクライアントは Java の jar ファイルです。このサーバーはワイヤープロトコルを直接再実装しているため、依存関係ツリーに JVM は一切ありません。Apple のリファレンス：Reporter ユーザーガイド。

開発

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

ローカルで実行します：

APPLE_PODCASTS_ACCESS_TOKEN=... APPLE_PODCASTS_VENDOR_ID=... npm start

テストでは fetch をスタブ化し、src/__tests__/fixtures/ にある手作業で作成したフィクスチャを使って実行します。Apple にアクセスするテストはありません。フィクスチャの列名を Apple のスキーマとして扱う前に、フィクスチャファイルの先頭にある由来を説明するコメントを読んでください。フィクスチャは解析、集計、日付、エラーの各処理を固定するためのもので、これがフィクスチャの目的です。Apple が文書化している応答形式に合わせて作成されたもので、アカウントから取得したものではありません。また、これを移植する際に参照した実装も、アカウントから取得したものではありません。

リリース

.github/workflows/publish.yml は、バージョン更新時に npm Trusted Publishing を使って公開します。Trusted Publishing は npmjs.com でパッケージごとに設定するため、初回の公開は手動で行う必要があります（npm publish --access public）。または、きめ細かなアクセス トークンを使用してください。パッケージが作成され、このリポジトリが信頼できる公開元として登録されるまでは、ワークフローは実行されますが、公開ステップで失敗します。手順はワークフローのヘッダーに記載されています。

コントリビューション

Issue やプルリクエストを歓迎します。特に役立つものは、次の順です。

• 実際のアカウントから得られる情報なら何でも。 このサーバーが解析するレスポンスは、実際の Apple データで検証されていません。実装は Apple のドキュメントを参照し、テストはフィクスチャで実行しています。実際のベンダー番号を指定して試した結果を、動作したかどうかも含めて教えてください。ほかの方法では埋められないギャップです。
• 実際のアカウントの列名。 気になる指標が unmappedColumns に表示された場合は、その列名を投稿してください。公開ドキュメントからは導き出せません。
• このサーバーが正しくマッピングできていない Reporter コード。 コードと Apple のメッセージを含めてください。

読み取り専用の契約を維持し、新しいツールの範囲は明確にしてください。範囲を明示し、行数に上限を設け、生データをそのまま出力しないでください。

概要

Conor Bronsdon が構築・保守しています。Chain of Thought ポッドキャストを配信しており、AI インフラ、開発者ツール、そして実務者が実際にこれらをどう使っているかを取り上げています。番組にとって重要なリスニングデータを Apple が保有している一方で、それを取得するためにサポートされている唯一の方法が Java の jar とスプレッドシートだったため、このツールを作りました。

関連ツール：

• op3-mcp：OP3 のダウンロード分析。地域、アプリ、エピソードごとのダウンロード数を確認できます。このツールが再生数を扱うのに対し、こちらはダウンロード数を扱います。
• Transistor MCP：Transistor.fm の公式 MCP サーバーです。エピソード、配信、分析に対応しています。
• podcastindex-mcp：Podcast Index の MCP サーバーです。人物やトピックによる検索、トレンド番組、フィードの健全性確認に対応しています。
• podcast-benchmark：公開データを基に、同業の番組と比較してベンチマークできます。
• ai-tools-for-creators：アイデアを仕事にしている人向けの、AI スキルと MCP サーバーを厳選したリストです。

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

---

免責事項

これは独立した個人プロジェクトであり、Apple Inc. とは提携しておらず、同社から資金提供や承認を受けていません。ここに記載された見解はすべて私個人のものです。

ライセンス

Apache-2.0