apple-podcasts-mcp

<div align="center">

# apple-podcasts-mcp

Owner-side Apple Podcasts analytics for AI agents: plays, followers, and per-episode listening, over the Apple Podcasts Connect Reporter protocol. Read-only.

[![npm version](https://img.shields.io/npm/v/@conorbronsdon/apple-podcasts-mcp?style=flat-square)](https://www.npmjs.com/package/@conorbronsdon/apple-podcasts-mcp)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=flat-square)](LICENSE)
[![Node](https://img.shields.io/badge/Node-20.19+-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
[![Glama score](https://glama.ai/mcp/servers/conorbronsdon/apple-podcasts-mcp/badges/score.svg)](https://glama.ai/mcp/servers/conorbronsdon/apple-podcasts-mcp)
[![Podcast](https://img.shields.io/badge/Podcast-Chain_of_Thought-purple?style=flat-square)](https://chainofthought.show/?utm_source=github&utm_medium=referral&utm_campaign=repo-readme&utm_content=apple-podcasts-mcp)
[![X](https://img.shields.io/badge/X-@ConorBronsdon-black?style=flat-square&logo=x)](https://x.com/ConorBronsdon)

</div>

---

An MCP server for the analytics Apple shows the person who owns the show: how many plays an episode got, how far into it people got, and whether the follower count is moving. That data lives behind Apple Podcasts Connect and the Reporter service, and it is not in Apple's public catalog API.

**Nothing here has been checked against a live Apple account.** The protocol is implemented from Apple's Reporter documentation and tested against fixtures written by hand. No request this server sends and no response it parses has been confirmed on the wire. If you run it against a real vendor number, an issue saying what came back is the most useful thing you can send.

**You need an Apple Podcasters Program membership to use this at all.** Reporter identifies you by a *vendor number*, and a vendor number is issued as part of the vendor relationship that Program enrollment creates. A standard free Podcasts Connect account does not have one: its Account → Details page shows an account UUID, which is a different identifier and will not work here. Enrollment costs an annual fee and requires a legal entity with tax and banking details. See [Availability of Apple Podcasts features](https://podcasters.apple.com/support/904-availability-of-apple-podcasts-features).

If you are not enrolled, there is nothing to configure and this server cannot help you — read your numbers in the Analytics section of Podcasts Connect instead.

**Read-only.** Reporter only reads. Nothing this server does can change a show, an episode, or an account.

## What this does not do

This is not the iTunes Search / public catalog API. It does not look up shows by name, read public charts, fetch artwork, or return reviews and ratings. The other "Apple Podcasts" MCP servers I have looked at wrap the public catalog, which needs no credentials. This one needs your vendor number and your access token, and in exchange it returns your own listening data.

It also does not cover:

- **Subscriptions and revenue.** Reporter has `apSubscriptionsSales` and friends. This server does not wrap them.
- **Anything before you had a Podcasts Connect account.** Reporter reports on what Apple recorded for your vendor number.
- **Today.** Apple publishes on a one-to-two day lag, so ranges default to ending two days back.
- **Downloads.** Apple reports plays and listeners, which are not downloads. If you want download counts, use a hosting or prefix analytics source such as [op3-mcp](https://github.com/conorbronsdon/op3-mcp).

## Tools

| Tool | What it returns |
|------|-----------------|
| `apple_podcasts_check_access` | Whether the token works, which vendor numbers it can read, and the token expiry when Apple returns one. No listening data. |
| `apple_podcasts_summary` | Show-level plays, unique listeners, engaged listeners, and followers over a date range, per period and totalled. Listener counts are devices, not people — see [What the metrics mean](#what-the-metrics-mean). |
| `apple_podcasts_episodes` | Per-episode plays and listener counts over a date range, rolled up across periods and ranked. |
| `apple_podcasts_followers` | Follower value per period across a range, with the change over the window. |

There is deliberately no "fetch the raw report" tool. Reporter returns one report per date, each with a row per episode and, in the non-worldwide variants, a row per storefront per episode. A month of that is tens of thousands of rows, and handing it to an agent verbatim is how you spend a context window on tab-separated text.

Every tool takes an explicit date range and a cap:

- `max_periods` limits how many Reporter calls a single tool call makes. Hard cap 31. Reporter has no range query — one date is one HTTP round trip — so this is a rate-limit guard, not a formality. A range wider than the cap is truncated to the **most recent** periods, and the response says so with `rangeTruncated`.
- `limit` on `apple_podcasts_episodes` caps returned rows at 50.
- Ranges default short: 7 days for Daily, 7 weeks for Weekly, 6 months for Monthly. Each default is sized to fit inside the default `max_periods` of 7, so a call with no dates returns a whole window rather than a truncated one.

## What the metrics mean

Apple's numbers are not headcounts. Podcasts Connect Analytics aggregates "listening and viewing completion rates from unique devices" ([Apple](https://podcasters.apple.com/support/5392-listener-analytics)), so a listener is a device. One person with a phone and a CarPlay head unit can be two.

- **Plays** — times someone pressed play on an episode.
- **Unique listeners** — devices that played more than zero seconds.
- **Engaged listeners** — devices that played at least **20 minutes or 40%** of an episode. That is Apple's threshold for depth. It is not a completion rate, and 40% of an episode is not finishing it.
- **Followers** — a level, not a flow. See [About the column names](#about-the-column-names) for why this one needs care.

## Setup

### 1. Get your vendor number and access token

Both come from the Reporter side of Apple Podcasts, which requires an **Apple Podcasters Program** membership — see the note at the top. A free Podcasts Connect account has neither.

Enrolled accounts get their vendor number and access token through Apple's Reporter tooling, documented in the [Reporter User Guide](https://help.apple.com/itc/podcastsreporterguide/en.lproj/static.html). Reporter's `generateToken` command issues the access token; `viewToken` shows the current one and its expiry.

Two constraints from Apple's documentation that will bite you:

- **One active token per Apple Account.** Generating a new token immediately expires the previous one. If anything else uses Reporter on this account — another tool, a colleague, a dashboard you set up last year — generating a token here silently breaks it, and the failure looks exactly like expiry.
- **Token management is not meant to be automated.** Apple states these commands "are not intended for automated use and access may be rate limited," so do not script rotation.

> **The `Settings` page this section used to point at does not exist.** An earlier version of these instructions said to find the vendor number and generate an access token under Podcasts Connect → Settings. Podcasts Connect has no Settings page. Its Account section has People, API Keys, and Details, and none of them carries a vendor number. Those instructions were written from Apple's documentation and never checked against the product.
>
> The **API Keys** page there is a different feature and not a substitute: Apple states an API key "allows your hosting provider to publish shows and episodes to Apple Podcasts on your behalf, but they will not have access to your listening analytics." Generating one grants this server nothing, and a key cannot be modified to add services after it is created.

### 2. Build it

Published on npm. The config blocks below use `npx`, which fetches it on first run; no clone required.

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

### 3. Configure your MCP client

#### Claude Code

Add to your `.mcp.json`:

```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

Add to `~/.codex/config.toml`:

```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

Same block as Claude Code, in `claude_desktop_config.json`.

The server starts without credentials so a client can list its tools. Each tool call then fails with a message telling you which variable is missing.

#### If your token can read more than one account

`APPLE_PODCASTS_ACCOUNT_ID` is optional and most setups do not need it. Set it when Reporter answers with code 214, "this token has access to more than one account; specify an account number" — Reporter will not pick one for you, so every call fails until you name it.

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

It is an environment variable rather than a tool argument because it is part of the credential, not part of a question: it does not vary between calls, and putting it in every tool's schema would spend context on an argument almost no one sets. Leave it unset if you have one account — Reporter rejects an empty account field, so the server omits it entirely rather than sending a blank. `apple_podcasts_check_access` echoes back the accou