Purpose

apple-podcasts-mcp is an MCP (Model Context Protocol) server that lets AI agents read analytics data belonging to show owners from Apple Podcasts Connect Reporter. It provides metrics such as play counts, unique listeners, engaged listeners, follower counts, and per-episode listening. This data sits behind Apple Podcasts Connect and the Reporter service and is not in Apple's public catalog API.

The server is read-only. Reporter itself only reads data, so the server cannot change shows, episodes, or accounts.

Main capabilities

Provides Apple Podcasts owner-side analytics data through MCP tools.
Supports date-range queries and limits the number of Reporter requests per tool call (hard cap 31).
Provides tools such as summaries, episode lists, and follower data.
Resolves column names for each metric through an alias table and reports resolvedColumns and unmappedColumns in responses.
Handles Reporter's numeric error codes and maps them to typed errors.
Supports the optional APPLE_PODCASTS_ACCOUNT_ID environment variable for multi-account scenarios.

Usage

Prerequisites

Using this server requires an Apple Podcasters Program membership. Reporter identifies users by vendor number, and the vendor number is obtained after membership registration. A standard free Podcasts Connect account does not have a vendor number; its Account → Details page shows an account UUID, which is a different identifier and cannot be used here. Membership registration requires an annual fee and requires a legal entity with tax and banking details.

If you are not registered as a member, no configuration is needed; this server cannot help, and you should view the data directly in the Analytics section of Podcasts Connect.

Obtaining the vendor number and access token

Both come from the Apple Podcasts Reporter side and require an Apple Podcasters Program membership. Registered accounts obtain the vendor number and access token through Apple's Reporter tool, as documented in the Reporter User Guide. Reporter's generateToken command issues an access token; viewToken displays the current token and its expiration time.

There are two constraints in Apple's documentation to note:

Each Apple Account can have only one active token. Generating a new token immediately expires the previous token. If something else on the account uses Reporter, generating a token will silently break it, and the failure will look exactly like expiration.
Token management should not be automated. Apple states that these commands are "not intended for automated use, and access may be rate-limited," so do not write rotation scripts.

Configuring the MCP client

This server is published on npm. The configuration block uses npx, which fetches automatically on first run, with no cloning required.

Add to .mcp.json:

{
  "mcpServers": {
    "apple-podcasts": {
      "command": "npx",
      "args": ["-y", "apple-podcasts-mcp"],
      "env": {
        "APPLE_PODCASTS_VENDOR_NUMBER": "你的vendor number",
        "APPLE_PODCASTS_ACCESS_TOKEN": "你的访问令牌"
      }
    }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.apple-podcasts]
command = "npx"
args = ["-y", "apple-podcasts-mcp"]

[mcp_servers.apple-podcasts.env]
APPLE_PODCASTS_VENDOR_NUMBER = "你的vendor number"
APPLE_PODCASTS_ACCESS_TOKEN = "你的访问令牌"

Claude Desktop's claude_desktop_config.json uses the same configuration block as Claude Code.

The server can also start without credentials so that the client can list its tools. Each tool call then fails and indicates which variable is missing.

APPLE_PODCASTS_ACCOUNT_ID is optional, and most setups do not need it. Set it when Reporter returns code 214 ("This token can access multiple accounts; please specify an account number"). Reporter does not automatically select an account, so every call will fail until an account is specified.

Verify access

Ask the assistant: "Check my Apple Podcasts access." This runs apple_podcasts_check_access, proves that the token is valid, and shows whether the vendor number can be read by the token.

Token rotation

Apple Reporter access tokens expire 180 days after they are generated. This is a problem that breaks setups, and it happens silently: the server continues to start, the tools continue to be listed, but every call begins to fail.

When the token expires, the tools return an error. Issue a new token using Reporter's generateToken. The old token stops working the moment the new token exists, so do this when you can update the configuration at the same time. Replace APPLE_PODCASTS_ACCESS_TOKEN and restart the MCP client.

Rotation is account-wide, not per application. Apple allows one active token per Apple Account. Other things on the account that communicate with Reporter will begin to fail when rotation occurs and report the same code 123. If multiple things need Reporter access, they must share one token and rotate together.

It is recommended to run apple_podcasts_check_access during setup and record the tokenExpires date (if Apple returns it). Not all accounts get an expiration time from Sales.viewToken; if not, the response will say so, and you should track the date yourself. Set a calendar reminder at 170 days.

When it applies

Podcast owners who want to let AI agents analyze their Apple Podcasts listeningData.
Need to understand single-episode play counts, deep listeners, and follower trends.
Want to combine Apple Podcasts analytics with other data sources for comprehensive analysis.

Limitations

Requires an Apple Podcasters Program membership; free accounts cannot use it.
Read-only; cannot change any data.
Does not query the public catalog, does not retrieve ratings or reviews, and does not involve subscription or revenue data.
Does not provide download counts; Apple reports plays and listeners, not downloads.
Data has a 1-2 day publishing delay; the date range ends two days ago by default.
There is no "get raw report" tool; all tools require an explicit date range and row limit.
The implementation is based on Apple's Reporter documentation and hand-written test fixtures, and has not been verified on a real Apple account.
Tokens expire every 180 days, and rotation is account-wide.
Column names are not hardcoded; they are resolved through an alias table, as Apple may rename columns.
Reporter is not REST; most failures return numeric codes under HTTP 200, and the server checks the response body.

Technical details

Reporter accepts HTTP POST containing a single form-encoded field, jsonRequest, which contains the token and a JSON document with a bracketed command. Version 2.2 matters: token-based authentication requires Reporter 2.2 or later. Successful reports are returned as gzip-compressed (Content-Type: application/a-gzip) tab-separated text, with one header row and no quotes.

When APPLE_PODCASTS_ACCOUNT_ID is set, the account field is added to the same JSON document. When it is not set, it is omitted: Reporter treats an empty account as an error rather than "no preference."

Apple's own client is a Java jar. This server directly reimplements the wire protocol, so there is no JVM in the dependency tree.

Tests use a stubbed fetch and run against hand-built fixtures in src/tests/fixtures/. No test touches Apple. The fixtures pin down parsing, aggregation, dates, and error paths.

.github/workflows/publish.yml uses npm Trusted Publishing to publish on version upgrades. The first release must be done manually or with a fine-grained access token.

Contributing

Issues and pull requests are welcome. Three things are especially useful: any feedback from a real account; column names from a real account; and Reporter codes that the server maps incorrectly. Keep the read-only contract, and keep new tools bounded—explicit ranges and row limits, no raw dumps.

apple-podcasts-mcp

About this tool