Apple Podcasts MCP Server & CLI

What is the Apple Podcasts MCP server & CLI?

The Apple Podcasts MCP server & CLI is a free, open source program that lets AI agents search Apple Podcasts, track chart ranks and read reviews for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Apple, or reads your library right on your Mac.

The CLI is the same program as commands. apple-podcasts-cli find-chart-position --show 1200361736 runs the same code your AI runs when you ask where a show ranks, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
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?
How many people played my episodes last week, and which one won?

The third one shows why this is useful. Apple caches a transcript excerpt for nearly every episode of every show you follow, and this lets your AI search them, so "where did I hear that" finally has an answer.

How to install the Apple Podcasts MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, and most of the tools need no account or key.

Set up your library and analytics

Nothing here is required. Each part is only for when you want it.

Read your own library

Your Podcasts library lives in a protected folder, so the app that runs the server needs Full Disk Access, once.

The library tools only exist on a Mac. On Windows and Linux the other 25 tools work as usual.

Add your show's analytics

This part is only for a show you own, and it's the one part with credentials.

The token expires after 180 days, and you make a new one in Podcasts Connect. The doctor tells you when it stops working.

Check that it works

Run the doctor. It checks each source on its own and names the one that fails, rather than leaving you with a vague error.

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

It also says whether your library holds any play data. On a Mac it usually doesn't, because listening progress stays on the device you listen on.

Use the Apple Podcasts CLI

The CLI is the same 32 tools as commands. AI 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 or a script.

Every tool name becomes a command with dashes, so find_chart_position runs as apple-podcasts-cli find-chart-position.

npm install -g @thenavidm/apple-podcasts-mcp-cli
apple-podcasts-cli
apple-podcasts-cli get-top-shows --limit 5
apple-podcasts-cli find-chart-position --show 1200361736 --storefronts us --storefronts gb
apple-podcasts-cli search-library --query "compound interest"

The bare apple-podcasts-cli lists every command, and apple-podcasts-cli <command> --help shows what a command takes. The OPML export asks for --confirm first, like it does for your AI.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both are the same program with the same 32 tools. The difference is when your AI pays for them, in the tokens it reads.

An app that loads every tool up front sends the full list with every message, whether you mention Apple Podcasts or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Apple Podcasts comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 190 tokens.

When the whole conversation is about Apple Podcasts, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't using it, with your AI app's own switch. APPLE_PODCASTS_LIBRARY=0 also takes the 7 library tools off the list.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on September 27, 2026 in Claude Code 2.1.257 with Claude Opus 5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

What Apple Podcasts actually does

Apple Podcasts isn't one API. It's several sources that share a brand, and 3 of them need nothing at all, which is why most tools work the moment it's installed.

Every country gives a different answer

The catalog, the charts and the reviews are all separate per country. An empty result in one country doesn't mean a show doesn't exist, so every answer says which country it came from.

The charts stop at 100

Apple publishes a top 100 per country, and there are no genre charts. A genre filter narrows the overall chart, and a show outside the top 100 has no rank to report.

Only published transcripts are readable

A show can link a full transcript in its RSS feed, and find_transcripts lists those, but most shows publish none. Apple's own transcripts in the app are locked, so search_library searches the short excerpts Apple caches for the shows you follow.

Your listening history stays on your phone

On a library synced from an iPhone, the play counts are zero, because progress is tracked on the device that played the episode. The tools say so rather than guessing what you've heard.

Analytics lag and count devices

Podcasts Connect reports run 1 to 2 days behind, so the analytics tools default to 3 days back. Listener counts are devices, not people, so one person on a phone and a HomePod counts twice.

Every Apple Podcasts tool

All 32 tools, grouped the way the repo groups them. 31 only read, and one saves a file on your computer.

Start here

Catalog

Charts and ranking

Reviews

Feeds

Research

Your library

Your show's analytics

Is the Apple Podcasts MCP server safe?

There's almost nothing to guard, because Apple Podcasts has no write API and this server doesn't invent one. Of 32 tools, 31 only read.

The one that writes, export_subscriptions, saves your subscriptions as an OPML file, so it asks for a confirm check first, marked Asks first in the tool tables above.

Make it read-only

Set APPLE_PODCASTS_READ_ONLY=1 and the OPML export disappears from the tool list. To keep your subscriptions out of it too, set APPLE_PODCASTS_LIBRARY=0, which removes the 7 library tools.

Keep a log of every write

Set APPLE_PODCASTS_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

There's no server of ours in between. Requests go straight from your computer to Apple and to podcast hosts, and nothing is collected.

Your library is read from the Podcasts app's own folder, read-only, and never written. Apple Podcasts Connect details stay in your app's config, and chart and catalog answers live in memory for 5 minutes.

Apple Podcasts MCP server settings

Every setting is optional, as an environment variable in your app's config.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.