Podcast Index MCP Server & CLI

Podcast Index MCP server and CLI for Claude Code, Codex and AI agents. 36 tools for podcast search, episode transcripts you can actually read and search, Podcasting 2.0 tags, value-for-value data, feed health and index stats.

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

It searches four million podcasts, and then it does the thing the API stops short of: it opens the transcript. Podcast Index hands out a link to an episode's transcript file and goes no further, which is useless to an assistant that cannot click. This fetches the file, works out whether it is SRT, WebVTT, JSON or HTML, and gives you the actual words with timestamps and speakers.

So you can ask when something was said, and get an answer.

There are 36 tools. One free key covers all but two of them.

Built 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

podcastindex-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:

podcastindex-cli                                          # every command, one line each
podcastindex-cli status                                   # what this server can reach
podcastindex-cli search-podcasts --q "ai agents" --max 5
podcastindex-cli get-trending --max 10
podcastindex-cli search-transcript --episode-id <id> --query "compound interest"
podcastindex-cli find-guest-appearances --name "Tim Ferriss"
podcastindex-cli check-feed-health --show https://example.com/feed.xml
podcastindex-cli submit-feed --feed-url https://example.com/feed.xml --confirm
podcastindex-cli <command> --help                         # what any command takes

--confirm is the shell spelling of the confirmation that adding a feed to the index needs. --json gives JSON, --compact puts it on one line, --select keeps only the fields you name, and --agent is compact JSON with no prompts, and never confirms a write. Exit codes are 0 ok, 1 an unexpected error, 2 usage or a hidden or refused write, 3 not found, 4 auth, 5 API, 7 rate limited and 10 nothing configured, so a script branches on the number.

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

MCP server, for your AI app

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

claude mcp add podcastindex \
  -e PODCASTINDEX_API_KEY=your_key \
  -e PODCASTINDEX_API_SECRET=your_secret \
  -- npx -y @thenavidm/podcastindex-mcp-cli@latest

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

A feed submission waits for your approval in the client, as section 9 explains.

Which one

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

What each costs

Both surfaces are the same program with the same 36 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 Podcast Index comes up or not. With the skill added, Claude Code also lists its one-line description, about 160 tokens.

To spend less, turn the server off when you are not using it, which in Claude Code is the /mcp panel. PODCASTINDEX_READ_ONLY=1 takes the 3 write tools off the list, leaving 33. 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 11,843 tokens instead of 13,095, tool search the same (1,253 against 1,253), and SKILL.md 60 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 finds the moment a phrase was said in an episode's transcript, and the flags it requires", read a median of 83,167 input tokens on 2.0.0 against 83,990 on 1.1.2 over the CLI, five runs each: Codex now asks which instead of reading the full command list. Over MCP, Codex prints the tool list with a script and cuts the printout to about 10,000 tokens, so it read about 9,020 on both versions, out of a full listing of 28,195 tokens on 2.0.0 against 28,239, and a median of 48,367 input tokens against 48,444.

Related MCP server: PodcastIndex MCP Server

Features

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

All 36 are in section 6.

Contents

1. What you can ask it 💬

• When did they talk about pricing on that episode, and what did they say?

• Read me this episode and pull out the three claims worth remembering.

• Where has this person been a guest, and what do they always get asked?

• Find me fifteen podcasts about indie games that are still publishing, and skip the dead ones.

• Is my feed broken? Downloads dropped last week and I do not know why.

• What is trending in true crime this week, in Swedish?

• Which of this show's episodes actually have transcripts?

• Who does this podcast split its listener payments with?

• Give me the chapter list so I can see if this episode is worth two hours.

• Tell me everything about this show in one go: cadence, guests, health, the lot.

The first one is the point. Podcast Index will tell you a transcript exists and give you a URL. No podcast tool reads it back to you. This one does, which is why "when did they say that" is a question you can now ask.

2. Quick install ⚡

Node 22 or newer. Nothing else.

npx -y @thenavidm/podcastindex-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/podcastindex-mcp-cli
podcastindex-cli

3. Setup 🔑

You need a key and a secret. Both. The key says who you are and the secret signs each request, so one without the other cannot authenticate. They are free, there is no approval step, and it takes about two minutes.

Have an agent do it

The agent cannot sign up for you. What it can do is wire up the config once you have the credentials and verify the connection.

Paste this into Claude Code, Cursor, or any agent with terminal access:

Set up the Podcast Index MCP server for me.

1. Open https://api.podcastindex.org/signup and tell me to fill it in. Wait for me.
2. When I paste the key and secret back, add the server to my client config
   with PODCASTINDEX_API_KEY and PODCASTINDEX_API_SECRET set.
3. Run the doctor command and tell me what it says.
4. If the clock check fails, tell me how to fix the clock. Do not tell me to
   regenerate the key.

Or do it yourself

Step 1. Go to api.podcastindex.org/signup.

Step 2. Fill in the form. You need an email address and a line about what you are building. There is no review and no waiting: the credentials appear immediately.

Step 3. Copy both values. The key is short and looks like UXKCGDSYGUUEVQJSYDZH. The secret is longer. Keep the secret private: anything holding it can spend your rate limit.

That is it. Everything except adding a podcast to the directory works now.

You do not need write permission. Write access is a separate grant, and 34 of the 36 tools do not use it. Only submit_feed and submit_feed_by_itunes_id need it, and they say so if you call them without it. Skip this unless you actually want to add feeds to the public directory.

To revoke a key, contact Podcast Index through the support links on podcastindex.org.

4. Connect your client 🔌

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

Claude Code

claude mcp add podcastindex \
  -e PODCASTINDEX_API_KEY=your_key \
  -e PODCASTINDEX_API_SECRET=your_secret \
  -- npx -y @thenavidm/podcastindex-mcp-cli@latest

Add --scope user to make 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 API key and secret, and whether to run it read only.

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

{
  "mcpServers": {
    "podcastindex": {
      "command": "npx",
      "args": ["-y", "@thenavidm/podcastindex-mcp-cli@latest"],
      "env": {
        "PODCASTINDEX_API_KEY": "your_key",
        "PODCASTINDEX_API_SECRET": "your_secret"
      }
    }
  }
}

Tip Claude Desktop does not inherit your shell PATH, so a bare npx can fail with "command not found". Use the absolute path from which npx if it does.

Quit Claude Desktop completely and reopen it.

claude.ai on the web

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

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

Host that somewhere with a public HTTPS URL and set PODCASTINDEX_HTTP_TOKEN, which the server requires before it will bind anything but loopback. A page from another site is refused unless PODCASTINDEX_HTTP_ALLOWED_ORIGINS lists it. Then in claude.ai: Customize, Connectors, +, Add custom connector, paste the URL, Add.

On Team and Enterprise an owner adds it first under Organization settings, Connectors, then each member enables it.

Cursor

.cursor/mcp.json, same JSON shape as Claude Desktop, key mcpServers.

Windsurf

~/.codeium/windsurf/mcp_config.json, key mcpServers.

VS Code

.vscode/mcp.json. The key is servers, not mcpServers, and each entry needs "type": "stdio".

{
  "servers": {
    "podcastindex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/podcastindex-mcp-cli@latest"],
      "env": {
        "PODCASTINDEX_API_KEY": "your_key",
        "PODCASTINDEX_API_SECRET": "your_secret"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml:

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

[mcp_servers.podcastindex.env]
PODCASTINDEX_API_KEY = "your_key"
PODCASTINDEX_API_SECRET = "your_secret"

Gemini CLI

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

Everything else

Any stdio MCP client takes the same three things: the command npx, the args, and the env block.

Or let the CLI write the entry, in each client's own format:

npx -y -p @thenavidm/podcastindex-mcp-cli podcastindex-cli install claude-code

It takes claude-code, codex, claude-desktop, cursor, vscode or gemini, and --dry-run shows the change first.

Every setting

Two are required. The rest have defaults that suit almost everyone, and are listed here so nobody has to read the source to find out what is tunable.

To disconnect, remove the entry from your client's config and restart the client. There is nothing installed globally to uninstall, since npx fetches it per run, and nothing on disk to clean up unless you configured an audit log.

5. Check it worked 🩺

npx -y @thenavidm/podcastindex-mcp-cli@latest doctor

Podcast Index doctor

  ✓ Node.js            v22.14.0
  ✓ Version            podcastindex 2.0.1
  ✓ Writes             on
  ✓ Tools              36 of 36 on
  ✓ Credentials        configured
  ✓ API key            set, 20 characters
  ✓ API secret         set, 40 characters
  ✓ Podcast Index API  reachable and authenticated, 4,312,880 feeds indexed
  ✓ Clock sync         2 seconds ahead, well inside the 180 second signing window

  Ready.

The clock line is the one to read. See below for why.

6. Tools 🛠️

Reading what is actually in an episode

The group worth installing this for. These leave Podcast Index and fetch files from the publisher's own host.

Questions instead of endpoints

Search

Shows and episodes

What is new and what is moving

Value for value

Health and size

Writes

7. What Podcast Index actually does 🧭

The things that will surprise you, and the reasons this server is shaped the way it is.

A wrong clock looks exactly like a wrong key

This is the one that costs people an hour.

Every request is signed with a SHA-1 of your key, your secret and the current unix timestamp, and Podcast Index accepts a three minute window either side of its own clock. A laptop that slept through a timezone change, a container with no time sync, or a VM restored from a snapshot will fail every single call with a 401.

A 401 reads as "bad credentials" to everybody, so the natural response is to regenerate a key that was never the problem.

doctor measures the drift against the server's own clock and says so. If it reports skew, fix the clock, not the credentials. On macOS:

sudo sntp -sS time.apple.com

Podcasting 2.0 tags are optional, and mostly absent

An empty result is a fact about that show, not a broken call. Nothing here can transcribe audio that was never transcribed, and retrying will not help.

This matters most for guest research. find_guest_appearances only sees shows that publish person tags, so a thin result is a floor on somebody's appearances and never a complete list.

Transcript files lie about their format

The feed declares a mime type and publishers get it wrong constantly: SRT served as text/plain, VTT declared application/json, JSON with an .srt extension.

So this server detects the format from the file body and treats the declaration as a hint. Trusting it would fail on a large minority of real shows.

Where a publisher offers several formats, JSON is preferred, because only the Podcasting 2.0 JSON format carries real speaker names. The same episode as SRT is usually an undifferentiated wall of text. Some SRT and VTT does carry speakers, as a NAME: prefix or a <v Name> span, and those are parsed out.

The transcript is not on Podcast Index

transcriptUrl and chaptersUrl point at files on the publisher's own server. So those tools fail for reasons that have nothing to do with the index: dead links, moved files, HTML error pages, hosts that time out.

When a transcript fetch fails, the podcaster's hosting is down. The index is fine and the call was correct.

A value block is not revenue

It says a show is configured to receive listener payments and names the wallets and their weights. It says nothing about whether anyone has ever paid.

Splits are relative weights, not percentages. A block of 90 and 10 is the same split as one of 9 and 1, so this server shows the computed share alongside the raw number.

Descriptions get silently truncated

Without the fulltext flag the API cuts every text field to 100 characters, and a description cut at 100 characters still looks like a description. A model reading one would summarize a show from its first sentence and never know the rest existed.

This server sets fulltext on every call that accepts it. You will not hit this, but it is why responses are larger than the raw API's.

An episode GUID is not unique

It is unique only inside its own feed. Look one up without saying which show, and the API answers with whichever it finds first, which is a coin flip. Pass show alongside guid on get_episode.

Feed ids and episode ids are different numbers. A feed id will not work where an episode id is wanted.

Adding a feed cannot be undone

submit_feed writes to a public global directory that hundreds of apps read, and this API has no delete. Removing something means asking the people who run Podcast Index.

That is why those two tools wait for your approval and notify_feed_update does not.

8. Your data 📦

There is no backend. Nothing is collected, and nothing is sent anywhere except the two places below.

Your secret is never transmitted. It is hashed into a signature locally and the hash is what travels.

Credentials live wherever your MCP client keeps its config, which is a plain JSON or TOML file on your own machine. This server writes nothing to disk unless you set PODCASTINDEX_AUDIT_LOG, and then only a line or two per attempted write.

Everything Podcast Index holds is public. There is no personal listening data here to leak, because the index does not have any.

9. Writing safely 🔒

Of 36 tools, 33 only read.

notify_feed_update asks the index to recrawl a feed sooner. It is idempotent, needs no credential, and is not guarded, because guarding harmless things trains the habit that makes real guards useless.

submit_feed and submit_feed_by_itunes_id add a podcast to a public directory and cannot be undone through this API. Both wait for your approval.

Over MCP a person approves each submit 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 to add that feed. PODCASTINDEX_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.

Read-only removes the tools rather than erroring on them, because a model cannot call a tool it cannot see, and an error is an invitation to retry differently.

On prompt injection. Transcripts, show notes and chapter titles are text strangers wrote, fetched from hosts nobody vetted, and anybody who can publish a podcast can put "ignore your instructions" into their own transcript. This server fences that text as data before a model reads it, and says so in its instructions.

That helps. It is not a guarantee. For an agent working unattended, PODCASTINDEX_READ_ONLY=1 is the real defense.

10. Troubleshooting 🔧

Run doctor first. It tests every credential and measures the clock.

11. FAQ ❓

An MCP server is a standard way to give an AI assistant real access to a tool, so it can act rather than guess. You install it once, your assistant gains the tools, and it works in Claude, Cursor, and anything else that speaks MCP.

Without one, an assistant asked about a podcast answers from whatever it absorbed in training. With one, it goes and looks.

podcastindex-cli is the same program as the MCP server, run 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, a script or a cron job. Every tool is a command with dashes, so get_trending runs as podcastindex-cli get-trending.

Use the MCP server in an app with no terminal, like Claude Desktop's chat. Use the CLI anywhere commands run: an agent like Claude Code, Codex or OpenCode, a script or a cron job. The MCP server's tools take up context on every message, and the CLI costs nothing until it runs.

Podcast Index is an open, free directory of podcasts. Around four million feeds, run independently of Apple and Spotify, with an API anybody can use.

It is also where Podcasting 2.0 lives: an open extension to RSS that lets publishers attach transcripts, chapters, guest credits, highlight clips and payment details to their episodes. That extra data is most of why this server is interesting.

Not in Claude Desktop: the .mcpb extension installs on a double click and asks for your free key. Elsewhere you paste a block of JSON into a config file, and step 3 walks through it. You can also hand the prompt in that section to an agent and let it do the wiring.

There is no backend and no telemetry. Your queries go to Podcast Index, and transcript fetches go to the publisher's own server. That is all.

Your API secret never leaves your machine. It is used to compute a signature locally, and only the signature is sent.

Read transcripts. The Podcast Index website will show you that an episode has a transcript and link to the file. It will not search inside it, and it will not search across episodes.

The other one is scale. "Find every episode this person has been on, grouped by show" is one call here and an afternoon by hand.

It cannot. Nothing here deletes anything, because the API has no delete.

The action worth knowing about is the opposite: submit_feed adds a podcast to a public directory permanently, and there is no way to remove it through this API. It waits for your approval for exactly that reason, and it needs a key with write permission that you will not have unless you asked for one.

It costs nothing. The server is MIT licensed and a Podcast Index API key is free with no approval step and no paid tier.

It works with any client that speaks MCP. Section 4 covers Claude Code, Claude Desktop, claude.ai, Cursor, Windsurf, VS Code, Codex CLI and Gemini CLI.

claude.ai is the one that works differently, because it runs connectors from Anthropic's cloud and needs the HTTP transport rather than a local command.

Podcast Index signs every request rather than using a bearer token. The key identifies you and travels with the request; the secret is hashed together with a timestamp to prove the request is yours and is recent.

The upside is the secret is never transmitted. The downside is the timestamp has a three minute window, so a drifting clock breaks everything. doctor checks for it.

Because the publisher did not attach one. Transcripts in podcasting are an optional RSS tag, and most shows do not use it.

Nothing here transcribes audio. If a show publishes no transcript, get_transcript cannot produce one, and it will say so rather than guessing at the content from the show notes.

Because a feed added to Podcast Index stays there: this API has no delete, and hundreds of podcast apps read the index. So submit_feed waits for you. Claude Code shows its own prompt, a client that can show forms asks with one, and in a terminal it is --confirm. An agent with no person to ask can be given PODCASTINDEX_CONFIRM=model, which lets its own confirm: true count.

Asking the index to recrawl a feed with notify_feed_update needs nothing, since doing it twice changes nothing.

With @latest in your client's config, npx fetches the newest version when the client starts the server, so there is nothing to update by hand. A global install updates with npm i -g @thenavidm/podcastindex-mcp-cli.

To remove it, delete its entry from your client's config and restart the client, or run npm uninstall -g @thenavidm/podcastindex-mcp-cli for a global install. It leaves nothing on disk unless you set an audit log.

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

• YouTube: @thenavidm and @thenavidai

• X: @thenavidm

• Instagram: @thenavidm

• LinkedIn: thenavidm

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

Dependencies

Data comes from Podcast Index, which is free and open. The Podcasting 2.0 namespace defines the transcript, chapter, person, soundbite and value tags this server reads.

Security

Found a vulnerability? Report it privately, not as a public issue. SECURITY.md covers what this server can reach, the write-safety model, and running it over HTTP.

License

MIT. Free to use, modify, and share.

Not affiliated with, endorsed by, or connected to Podcast Index LLC.

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