Apple Podcasts MCP Server & CLI README

Apple Podcasts MCP Server & CLI

Apple Podcasts MCP server and CLI for Claude Code, Codex and AI agents. 32 tools for podcast search, chart rank tracking, listener reviews, RSS feed parsing and validation, on-device transcript search, and Apple Podcasts Connect analytics.

One install gives you both surfaces, the same 32 tools under the same names, reading one array of tool definitions so they cannot drift apart.

It searches Apple's catalog and checks where a show ranks in each country.

It reads listener reviews and parses any podcast's RSS feed.

If you own a show, it pulls your listening numbers too.

Nothing here needs an account, except the owner analytics.

There are 32 tools, and only the five that read your own show's analytics need an account of any kind.

Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI.

Two ways to use it

Command line

apple-podcasts-cli runs every tool as a command. Agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal, a script or a cron job:

apple-podcasts-cli                                     # every command, one line each
apple-podcasts-cli status                              # what this server can reach
apple-podcasts-cli get-top-shows --limit 5             # Apple's Top Shows chart
apple-podcasts-cli find-chart-position --show 1200361736 --storefronts us --storefronts gb
apple-podcasts-cli get-reviews --show 1200361736 --storefront gb
apple-podcasts-cli search-library --query "compound interest"
apple-podcasts-cli check-feed --show https://example.com/feed.xml
apple-podcasts-cli find-chart-position --show 1200361736 --json --select best_rank,charted_in
apple-podcasts-cli export-subscriptions --path ~/Desktop/podcasts.opml --confirm
apple-podcasts-cli <command> --help                    # what any command takes

--confirm is the shell spelling of the confirmation the OPML export needs. --json gives JSON, --compact puts it on one line, --select keeps only the fields you name, and --agent turns on all of it for a script. Exit codes are 0 ok, 1 unexpected, 2 usage or a refused write, 3 not found, 4 auth, 5 API, 7 rate limited and 10 nothing configured, so a script branches on the number.

apple-podcasts-cli schema <command> prints the exact JSON Schema an MCP client receives for that tool.

MCP server, for your AI app

apple-podcasts-mcp is what Claude Code, Claude Desktop, Cursor and the rest launch. You never run it by hand:

claude mcp add apple-podcasts -- npx -y @thenavidm/apple-podcasts-mcp-cli@latest

In Claude Desktop, the .mcpb extension installs on a double click. Section 4 has every other client.

Then just ask: "where does this show rank in the US, UK and Sweden, and what do its reviews complain about?" The one tool that writes, the OPML export, waits for your approval in the client, as section 11 explains.

Which one

They are the same program reading the same tool definitions, so anything one can do, the other can.

Features

Every tool is both a command and an MCP tool, with the same name. The command is the tool name with dashes.

All 32 are in section 7.

Contents

1. What you can ask it 💬

• Where does this show rank in the US, UK and Sweden, and where is it strongest?
• What are people complaining about in the reviews of my competitor's show?
• Which episode was that thing about compound interest I heard a while back?
• Compare these four shows on rank, ratings and how often they publish.
• Is my podcast feed missing anything Apple requires?
• What is trending in podcasts right now that is not true crime?
• Find shows like this one, so I can see who else is in this niche.
• Which of the shows I follow publish real transcripts I can read?
• How many people played my episodes last week, and which one won?
• Export everything I subscribe to as OPML so I can leave Apple Podcasts.

The third one is the point. Apple caches a transcript excerpt for nearly every episode of every show you follow, and nothing surfaces it. On a normal library that is tens of thousands of excerpts of real spoken words sitting on your Mac, searchable, and it answers "where did I hear that" in a way no catalog can.

2. Quick install ⚡

Node 22 or newer. Nothing else.

npx -y @thenavidm/apple-podcasts-mcp-cli@latest --version

That is the whole install. npx fetches it on demand, so there is nothing to update later.

For the CLI as a command you or your agent can run anywhere, install it once:

npm install -g @thenavidm/apple-podcasts-mcp-cli
apple-podcasts-cli

Most of this server works immediately, with no account. Apple's catalog, its charts, its reviews and every podcast RSS feed are all open. Your own library is read straight off this Mac. Section 3 is only for the parts that need something extra, and you can skip it entirely.

3. Setup 🔑

Nothing here is required. Skip to section 4 and come back when you want one of these.

Reading your own library

Nothing to configure, but macOS may need to be told to allow it.

The Apple Podcasts library lives in a protected group container, so the app running the server needs Full Disk Access:

1. Open System Settings, then Privacy & Security, then Full Disk Access.
2. Click + and add the app that launches the server. For Claude Code or Codex that is your terminal (Terminal, iTerm, Ghostty). For Claude Desktop it is Claude itself.
3. Quit that app completely and reopen it. The permission is only read at launch.

If you would rather this server never read your subscriptions, set APPLE_PODCASTS_LIBRARY=0 and those seven tools disappear from the list entirely.

This group only exists on macOS. On Linux or Windows the other 25 tools work normally.

Apple Podcasts Connect analytics

Only for a show you own and administer. It is the one part with credentials.

1. Sign in to podcastsconnect.apple.com.
2. Your vendor number is on the account. It is a numeric id, usually seven or eight digits.
3. Generate a Reporter access token under the account's Reporter settings. Copy it immediately: Apple shows it once.
4. Set both as environment variables in your client config, as APPLE_PODCASTS_VENDOR_NUMBER and APPLE_PODCASTS_REPORTER_TOKEN.

The token expires after 180 days and has to be regenerated in Podcasts Connect. Nothing in this server can mint or refresh one. doctor reports whether the token still works, and check_analytics_access lists which vendor numbers it can actually read, which is the fastest way to tell a wrong token from a wrong vendor number.

To revoke it, delete the token in Podcasts Connect. That takes effect immediately.

Have an agent do it

The agent cannot sign in to Apple for you. What it can do is wire up the config and verify it. Paste this into Claude Code, Cursor, or any agent with terminal access:

Set up @thenavidm/apple-podcasts-mcp-cli for me.

1. Add it to my MCP client config, running via `npx -y @thenavidm/apple-podcasts-mcp-cli@latest`.
2. Run `npx -y @thenavidm/apple-podcasts-mcp-cli@latest doctor` and show me the output.
3. If the local library check fails on permissions, tell me exactly which app
   to add to Full Disk Access and stop so I can do it.
4. Do not ask me for Apple Podcasts Connect credentials unless I say I own a
   show. Everything else works without them.

4. Connect your client 🔌

The long version, every step with what to do when one fails, is in INSTALL.md.

Every block is self-contained. No credentials are needed in any of them; the env block is only for the optional extras from section 3.

Claude Code

claude mcp add apple-podcasts -- npx -y @thenavidm/apple-podcasts-mcp-cli@latest

--scope user makes it available in every project rather than the current one.

Claude Desktop

The short way: download the .mcpb extension from the latest release and double-click it. It carries its own dependencies, so there is no config file to edit and nothing to install first. Claude Desktop asks for your country and, only if you own a show, your Apple Podcasts Connect details. For the library tools, give Claude Desktop Full Disk Access (section 3).

The long way, if you would rather edit the config yourself:

1. Open the config file.

In Claude Desktop go to Settings, then Developer, then click Edit Config. That reveals claude_desktop_config.json in your file manager. Open it in any text editor.

To go straight there:

On macOS, from a terminal:

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Add the server.

If the file is empty or does not exist, paste this whole thing in:

{
  "mcpServers": {
    "apple-podcasts": {
      "command": "npx",
      "args": ["-y", "@thenavidm/apple-podcasts-mcp-cli@latest"]
    }
  }
}

If you already have other servers, add only the "apple-podcasts": { ... } part inside your existing "mcpServers", and put a comma after the entry before it. The file has to stay valid JSON. One missing comma or one trailing comma stops every server from loading, not just this one.

Tip Claude Desktop does not inherit your shell PATH. If npx is not found, run which npx in a terminal and use that absolute path as the command.

3. Restart properly.

Quit Claude Desktop completely and reopen it. On macOS closing the window is not enough, use Cmd+Q. On Windows quit it from the system tray. Claude only reads that file at startup.

4. Check it worked.

Look for the tools icon in the message box and click it. You should see apple-podcasts with its tools listed. Then ask it something from section 1.

If nothing appears, Claude Desktop's own log is the fastest way in:

tail -n 50 ~/Library/Logs/Claude/mcp-server-apple-podcasts.log

Cursor

.cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project. Same JSON shape as Claude Desktop, with the key mcpServers. Then reload the window, or open Settings, MCP, and toggle the server.

Windsurf

~/.codeium/windsurf/mcp_config.json, key mcpServers, same JSON shape. Then reload.

VS Code

.vscode/mcp.json. The key is servers, not mcpServers, and each entry takes a type:

{
  "servers": {
    "apple-podcasts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/apple-podcasts-mcp-cli@latest"]
    }
  }
}

Or run MCP: Add Server from the command palette.

Codex CLI

~/.codex/config.toml:

[mcp_servers.apple-podcasts]
command = "npx"
args = ["-y", "@thenavidm/apple-podcasts-mcp-cli@latest"]

Gemini CLI

~/.gemini/settings.json, key mcpServers, same JSON shape as Claude Desktop.

claude.ai on the web

claude.ai runs connectors from Anthropic's cloud rather than your machine, so it needs a public HTTPS URL and cannot run a local command.

npx -y @thenavidm/apple-podcasts-mcp-cli@latest --http --port 8000

Host that somewhere with a public HTTPS URL, then in claude.ai: Customize, Connectors, +, Add custom connector. Paste the URL and click Add.

The library tools cannot be hosted. They read the Apple Podcasts database on whatever machine the server runs on, so a hosted instance would serve your subscriptions to every caller. The server refuses to start bound to anything but loopback while the library is enabled. Set APPLE_PODCASTS_LIBRARY=0 to host the 25 public tools.

Set APPLE_PODCASTS_HTTP_TOKEN so the endpoint is not open, and put it behind TLS. GET /health reports the tool count and capability without authentication.

Docker

docker build -t apple-podcasts-mcp .
docker run --rm -i apple-podcasts-mcp

The container has no Apple Podcasts library, so it runs the public tools only.

Everything else

Any stdio MCP client takes the same three things: the command npx, the args, and optionally an env block. Zed, Cline and Continue all work.

5. Check it worked 🩺

npx -y @thenavidm/apple-podcasts-mcp-cli@latest doctor

It probes each of the four sources separately and names the failing one, rather than leaving you with "the tool errored". It also checks two things this server assumes but cannot guarantee: that the Podcasts database still has the columns it reads, and whether your library holds any usable play data.

Two things account for most failures:

6. What it costs to have connected

Both surfaces are the same program with the same 32 tools. The difference is when the model pays for them. Measured in Claude Code:

Claude Code's tool search is on by default: it sends only the tool names and the server instructions, and loads a tool's full definition when the model reaches for it. An app that loads every tool up front pays the first line on every message, whether Apple Podcasts comes up or not. With the skill added, Claude Code also lists its one-line description, about 190 tokens.

To spend less, turn the server off when you are not using it, which in Claude Code is the /mcp panel. APPLE_PODCASTS_LIBRARY=0 takes the 7 library tools off the list. Or install the CLI and add the server on the days it earns its place.

Measured on 2026-10-05 with Claude Code 2.1.286 on Claude Opus 5.5: one short prompt with and without the server connected, once with ENABLE_TOOL_SEARCH=false and once with the default, the difference read from the API's own usage figures. SKILL.md was measured the same way. Other apps and models count tokens a little differently.

Against 1.1.2, measured the same day: every tool loaded costs 12,701 tokens instead of 13,764, tool search the same, and SKILL.md 51 more, because it now says how approval works over MCP and lists every exit code. In Codex 0.159.3 on gpt-6.1-sol, the same task, "find the command that shows where a podcast ranks on Apple's charts across several countries and the flags it requires", read a median of 84,197 input tokens on 2.0.0 against 84,531 on 1.1.2 over the CLI, and 48,263 against 48,262 over MCP, five runs each. Codex prints the tool list from a script and keeps the same share of it on both sides; the part it kept was two tokens longer on 2.0.0 (8,928 against 8,926), which is the whole difference.

7. Tools 🛠️

32 tools. Everything that reads Apple's catalog takes an optional storefront. Anywhere a show is named, it takes an Apple id or a pasted Apple Podcasts URL, so a link someone sent you works directly.

Start here

Catalog

Charts and ranking

Reviews

Feeds

Research

Your library

macOS only. Hidden entirely by APPLE_PODCASTS_LIBRARY=0.

Owner analytics

Needs Apple Podcasts Connect credentials. Listed even when unconfigured, so they can tell you what is missing.

Resources and prompts

Three resources, so a client can load context without spending a tool call: apple-podcasts://status, apple-podcasts://concepts, apple-podcasts://output-format.

Four prompts: show-teardown, niche-map, what-did-i-hear, feed-checkup.

8. The four sources 📚

Apple Podcasts is not one API. It is four things wearing the same brand, and they differ in who can reach them and what they are good for. This is the single most useful thing to understand about this server.

Three of those need nothing at all. That is unusual and it is why this works the moment you install it.

9. What Apple actually does ⚠️

The section that makes this worth more than the API docs it wraps. Everything here was verified against the live services, not recalled.

Storefronts change the answer, silently

The catalog, the charts and the reviews are all per country. The same search in us and se returns different shows in a different order, a show can be published in one market and not another, and its review pool is entirely separate in each.

An empty result in one storefront is not evidence a show does not exist. Every listing here carries the storefront it came from for exactly this reason.

Ranking stops at 100, and there are no genre charts

Apple publishes two charts per storefront: Top Shows, which is follower-weighted and slow, and Trending Episodes, which moves fast and is the better read on what a topic is doing this week. Both cap at 100 and asking for 200 fails.

A genre-scoped chart returns 404. Apple serves one overall chart per country. The genre argument on get_top_shows filters that list, so it gives the charting shows that happen to be in a genre, not that genre's own top 100.

There is also no endpoint for "where does this show rank". Finding a rank means fetching the chart and looking, which is what find_chart_position does, once per storefront.

The Search API answers 200 for failures

A malformed query returns HTTP 200 with an errorMessage field and zero results. Handled by status alone that reads as "nothing matched", and a model told a search found nothing concludes the show does not exist. Every response here is inspected on success, not only on failure.

Rate limiting is real, silent, and has no header

Roughly 20 requests a minute per IP, answered with 403 and an HTML body. No Retry-After, no quota endpoint, no announcement.

Requests are therefore spaced and queued rather than fired in parallel, and responses are cached for five minutes, so asking about six shows fetches the chart once rather than six times. Prefer get_show_profile and compare_shows over calling single tools in a loop.

Transcripts: two kinds, one readable

Feed transcripts are public. <podcast:transcript> in a show's RSS carries a URL to a VTT, SRT or JSON transcript that anything can fetch. find_transcripts lists them. Most shows publish none, which is the show's choice.

Apple's own transcripts are not readable. The ones the app displays are access-controlled, and their CDN refuses unauthenticated requests. What does exist is a short excerpt Apple caches locally for episodes in your library, speaker-tagged and typically a few hundred characters, present for nearly every episode. search_library searches those. It is an excerpt, not the episode, and the tools say so rather than implying otherwise.

Your library holds far more than the app shows

The Podcasts app keeps a Core Data store with every episode of every show you follow: full descriptions, dates, durations, guids and audio URLs, whether or not anything was ever downloaded. On a normally-used library that is tens of thousands of episodes.

Its dates are Core Data timestamps, which are seconds since 2001, not 1970. Read as Unix time, every date in your library lands in 1970.

Play data usually is not there. On a library synced from an iPhone, the playhead and play-count columns are zero on every row. Listening progress is tracked on the device that played the episode and does not reach the Mac. So nothing here can tell you what you have listened to. library_stats reports whether your library actually has usable play data, and the tools decline to infer listening history rather than presenting a zero as a finding.

Podcasts Connect lags, and counts devices

Reporting is one to two days behind, and a request for today returns an error that reads as breakage. Every analytics tool here defaults to three days back.

Listener counts are devices, not people. One person on a phone and a HomePod counts twice, and Apple has no way to collapse them.

The access token expires after 180 days with no refresh path.

10. Your data 🔒

There is no server behind this. Your requests go straight from your machine to Apple and to podcast hosts, and nothing is collected or sent anywhere else.

The library database is opened read-only through an immutable URI, which is also why reads work while the Podcasts app is running.

Hosts contacted: itunes.apple.com, rss.marketingtools.apple.com, reportingitc-reporter.apple.com if you configure analytics, and whatever host serves a podcast RSS feed you ask for.

11. Safety 🛡️

Short, because there is almost nothing to guard. There is no Apple Podcasts write API and this server does not invent one. Of 32 tools, 31 only read.

export_subscriptions writes an OPML file and overwrites whatever is at the path, so it waits for your approval. That is the only guard, deliberately: approval on every call would train people and models to approve reflexively, which is worse than not asking.

Over MCP a person approves the export where the client can ask: Claude Code (2.1.246 and later) shows its own prompt, and a client that can show forms asks with an approval form whose one box starts unticked. Each approval is signed, bound to that exact call and works once. Where a client can do neither, the model's confirm: true counts, and it should pass it only when you asked for that export. APPLE_PODCASTS_CONFIRM=model makes confirm: true enough everywhere, for an agent with no person to ask. In a terminal it is --confirm, which --agent never adds.

The control that matters here is privacy rather than damage:

APPLE_PODCASTS_LIBRARY=0     # removes all seven library tools from the list
APPLE_PODCASTS_READ_ONLY=1   # removes the OPML export too
APPLE_PODCASTS_AUDIT_LOG=~/.apple-podcasts-mcp/writes.jsonl

Tools disappear from the list rather than erroring when called, because a model cannot call a tool it cannot see.

Prompt injection. Reviews are the most injectable surface here, and "summarize my reviews" is the first thing anyone asks. Review bodies, show notes and transcript excerpts are all fenced with a marker naming them as data before a model reads them, and any attempt to close that fence early is defanged. The server instructions repeat the rule. That framing helps and it is not a guarantee: for an agent working unattended over other people's text, APPLE_PODCASTS_READ_ONLY=1 is the real defense.

12. Troubleshooting 🔧

doctor first. It names the failing source and the fix.

13. FAQ ❓

Environment variables

Versions

See CHANGELOG.md.

Questions

Run into a problem or have a question? Open an issue and I will help.

About the author

Navid Moazzez is a leading AI business strategist, and the host of the AI Creator Summit, watched by 100,000+ creators. He helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life. He creates useful free tools, MCP servers and CLIs that creators and founders can use in their own workflows.

Links

• Personal website: navid.me
• Navid Media: navid.media
• YouTube: @thenavidm and @thenavidai
• X: @thenavidm
• Instagram: @thenavidm
• LinkedIn: thenavidm

If this is useful, star the repo and come say hi on X.

Dependencies

RSS parsing and SQLite reading are both built in, so there is nothing else to install. The library is read through Node's own node:sqlite where available, falling back to the sqlite3 command that ships with macOS.

License

MIT. Free to use, modify, and share.

Not affiliated with, endorsed by, or connected to Apple Inc.

© 2026 Navid Media. Made with ❤️ by Navid Moazzez.