---
name: podcaststotext
description: Transcribe podcasts, YouTube and TikTok videos, and audio files to text, then generate show notes, chapters, translations and published episode pages from the result. Use when the user asks about the contents of a podcast episode or a video, wants a transcript, or wants something made out of one.
homepage: https://podcaststotext.com/mcp
license: MIT
---

# PodcastsToText

13 tools over the Model Context Protocol (server version 2.2.0):
find a show's feed, transcribe an episode, and turn the transcript into show
notes, chapters, translations or a published page.

Use this skill when the user asks what was said in a podcast or video, asks for a
transcript, or asks for anything derived from one. It is not useful for audio the
user has not pointed you at.

## 1. Check the server is connected

The tools below are exposed by a remote MCP server. Before anything else, look at
the tools you already have. If you can see `transcribe_podcast`, you are
connected, skip to section 3.

## 2. Connect it

The server is remote HTTP, so there is nothing to install and no process to keep
alive.

**In the Claude app (web, desktop, mobile) or ChatGPT**, the user adds it as a custom
connector with the URL `https://podcaststotext.com/api/mcp` and signs in on podcaststotext.com when asked.
There is no API key on that path, so do not ask for one.

**In every other client** it needs an API key, which the **user** must create at https://podcaststotext.com/dashboard/api-keys, never invent one, and never ask them to paste it into a chat message where it
will sit in the transcript. Have them put it in the config themselves.

```bash
claude mcp add --transport http podcaststotext https://podcaststotext.com/api/mcp \
  --header "Authorization: Bearer ptt_your_key_here"
```

For a client that reads a JSON config file instead:

```json
{
  "mcpServers": {
    "podcaststotext": {
      "type": "http",
      "url": "https://podcaststotext.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ptt_your_key_here"
      }
    }
  }
}
```

Other clients want the same information under different keys, `servers` rather
than `mcpServers` in VS Code, `serverUrl` in Windsurf, TOML in Codex. The full
set is at https://podcaststotext.com/mcp.

## 3. Four rules that will otherwise cost the user money or a conversation

**Rule 1. Never fetch a full transcript you were not asked for.** `get_transcript`
returns a ~1,500 character preview and the total length. Pass `full=true` only when
you actually need the whole body. A two-hour episode is comfortably 60,000
characters; pulling that in speculatively can end the conversation. If you need one
fact out of a long transcript, use `search_my_transcripts` instead.

**Rule 2. Transcribing spends the user's credits.** Check `get_usage` before a long
episode or a batch, and tell the user what a job will cost them before starting it if
they have not already agreed to it. A transcription that *fails* is not charged, but
one you started for no reason is. There should be a human in the loop on the first
few of these.

**Rule 3. Nothing blocks on audio.** `transcribe_podcast` returns an id in under a
second and the audio is processed in the background. Poll `get_transcript` after
about 30 seconds, and again on a widening interval, do not busy-loop, and do not
tell the user it failed because the first poll said `processing`.

**Rule 4. Read the refusal, do not retry it.** When a tool refuses, it returns an
instruction rather than an opaque error. A Spotify *show* link cannot be resolved to
a feed (Spotify publishes no route to one) and a YouTube link is not a podcast feed:
in both cases search by show name with `get_rss_feed`, or use an Apple Podcasts link
or a direct audio URL. Calling the same tool again with the same argument will fail
the same way.

## 4. The usual chain

Most requests are one of these, and each step's result names the next:

```
"What did <show> say about <topic>?"
  get_rss_feed → lookup_podcast → transcribe_podcast → get_transcript (poll)
  → search_my_transcripts

"Get subtitles for <episode>"
  lookup_podcast → transcribe_podcast
  → GET /api/v1/transcriptions/{id}?format=srt   (REST, not MCP)

"Write show notes for <episode>"
  lookup_podcast → transcribe_podcast → get_transcript (poll)
  → generate_show_notes → generate_chapters
```

Two shows share a name more often than you would expect. `get_rss_feed` returns
several candidates with their authors: show them to the user and let them pick
rather than guessing at the first one.

## 5. Tool reference

The API and the MCP server are on Creator, Pro, Studio and Podmaxxing. A free account cannot reach this server at all, and its
key creation is refused in the dashboard rather than at the first call. Of the tools below,
10 work on any plan that has access; the remaining 3 additionally need
the AI tools and refuse with that in the message rather than an opaque error, so do not retry them.

### Discovery

Turn a show name or a store link into the RSS feed and audio URL everything else needs. YouTube and TikTok links resolve straight to their single video; Spotify shows are refused here, with an explanation the model can act on.

| Tool | Plan | What it does | Inputs (* = required) |
|---|---|---|---|
| `get_rss_feed` | Any | Resolve a show name, Apple Podcasts link or Spotify link to its RSS feed. A Spotify link is resolved through the Apple directory, since Spotify publishes no feed of its own. Returns several candidates when the name is ambiguous rather than guessing. YouTube and TikTok have no feed, send those straight to transcribe_podcast. | `podcast`, `url` |
| `lookup_podcast` | Any | Read a feed into show metadata and recent episodes, each with the direct audio URL that transcribe_podcast needs. A Spotify link resolves to the show's public feed first, and to the episode it named. A YouTube or TikTok link resolves to its single video instead. | `url`*, `episode` |

### Transcription

The core loop. Transcription is asynchronous: you get an id back immediately and poll for the result, so a long episode never blocks the conversation.

| Tool | Plan | What it does | Inputs (* = required) |
|---|---|---|---|
| `transcribe_podcast` | Any | Start transcribing a direct audio URL, or a YouTube, TikTok, Spotify or Apple Podcasts link. Returns an id straight away: it never waits for the audio. YouTube comes back already completed, read from the video's caption track, and costs nothing; everything else spends the account's credits. | `audio_url`*, `title`, `language` |
| `get_transcript` | Any | Fetch one transcription and its status. Returns a 1,500-character preview unless you ask for the full body, so a long episode cannot flood the context window by accident. | `id`*, `full` |
| `list_transcripts` | Any | Browse the account's transcriptions, newest first. Metadata only, never transcript bodies. | `limit`, `status` |
| `search_my_transcripts` | Any | Find an episode by keyword across titles and generated show notes: the "which episode was about X" question. Does not search the full transcript text. | `query`*, `limit`, `include_unfinished` |

### Manage

Destructive operations, kept in their own group so a model reading the list sees that they are not part of the ordinary flow.

| Tool | Plan | What it does | Inputs (* = required) |
|---|---|---|---|
| `delete_transcript` | Any | Permanently delete one transcript and its stored file. Not undoable and does not refund credits. Confirm with the user first. | `id`* |

### Account

What the account has left, so an agent can check before committing to a long episode or a batch.

| Tool | Plan | What it does | Inputs (* = required) |
|---|---|---|---|
| `get_usage` | Any | Report the plan and remaining transcription credits, in minutes. | — |

### AI content

Everything you would otherwise write by hand from a finished transcript. They run against the API key's owner, and all but translation cache their result.

| Tool | Plan | What it does | Inputs (* = required) |
|---|---|---|---|
| `generate_show_notes` | Paid plan | A summary plus bullet points for a completed transcription. Cached, so a second call is cheap. | `id`* |
| `generate_chapters` | Paid plan | Timestamped chapter markers: a title and a start time per section. | `id`*, `force` |
| `translate_transcript` | Paid plan | Translate a completed transcript into another language, returned directly. Cached per language, so a repeat request is free. Each transcript may hold a limited number of distinct languages; the response reports the limit. | `id`*, `language`*, `force` |

### Publish

Tools that act on something outside the transcript itself: a public page, or an endpoint that gets told when things happen.

| Tool | Plan | What it does | Inputs (* = required) |
|---|---|---|---|
| `publish_episode` | Any | Put an episode's transcript on a public page at /p/{show}/{episode}. Refused for shows whose ownership has not been verified, because it publishes under the user's name. | `episode_id`* |
| `manage_webhook` | Any | List, create or delete webhook endpoints, so an agent is told when work finishes instead of polling for it. The signing secret is shown once, on create. | `action`*, `url`, `events`, `id` |

## 6. Beyond MCP

The same key works for the REST API (`https://podcaststotext.com/api/v1/openapi.json`) and for
webhooks, which is the better fit for anything long-running or unattended, transcription completion arrives as a delivery instead of a poll.

- Endpoint: `https://podcaststotext.com/api/mcp`
- Auth: OAuth sign-in (connectors), or `Authorization: Bearer ptt_your_key_here`
- Server card: `https://podcaststotext.com/.well-known/mcp/server-card.json`
- Docs: https://podcaststotext.com/mcp