Spoken

Spoken — podcast transcript API and MCP server, clean Markdown with real speaker names

Spoken is a transcript API that turns any published podcast into clean Markdown with real speaker names — not "Speaker 1." One API call returns named, timestamped text, ready for LLMs, RAG pipelines, summarizers, and search. This repo also ships spoken-mcp, an MCP server that gives Claude Desktop, Claude Code, Cursor and Cline the same transcripts as tools — see Use as an MCP server.

It's a transcript retrieval API, not a speech-to-text service: it works on already-published podcasts, so you skip uploading audio, running diarization, and mapping anonymous speaker labels by hand. For published shows that's typically 5–10× cheaper than running the audio through a transcription service.

• 🎙️ Real speaker names, resolved automatically
• 📄 Clean Markdown with timestamps, tuned for LLM context windows and RAG chunking
• 🔎 Search by text query or paste a Spotify/YouTube URL
• 💳 Pay-per-use credits — no subscription, failed calls never charged, repeat fetches free
• 🤖 Agent-native — ships with an Agent Skill, agents.md, llms.txt, and an OpenAPI spec

Get a key at spoken.md — or try it free with the demo key pt_demo (search works fully; transcripts limited to the demo episode).

Quickstart

# 1. Find an episode (by text, or paste a Spotify/YouTube URL)
curl -s 'https://spoken.md/search?q=huberman+sleep' \
  -H 'x-api-key: pt_demo'

# 2. Fetch the transcript as Markdown
curl -s 'https://spoken.md/transcripts/1000651996090' \
  -H 'x-api-key: pt_demo'

The transcript comes back as Markdown with named speakers and timestamps:

**John Smith** (0:00)
Welcome to the show. Today we're talking about...

**Jane Doe** (0:15)
Thanks for having me.

Endpoints

Method & path	What it does	Credits
GET /search?q={query or URL}	Find episodes; returns id, title, podcast, podcastId, date	0
GET /podcasts/{podcastId}/episodes	List a show's full back catalog; returns every episode's id, title, date	0
GET /transcripts/{id}	Return the Markdown transcript	1 on first fetch, 0 on repeat
GET /balance	Current credit balance + usage history	0
GET /following	The shows this key keeps up with (inferred from fetches, or declared with PUT / dropped with DELETE /following/{podcastId})	0
GET /new	New episodes on those shows that have not been fetched yet, each with a transcript URL; ?format=atom for a feed	0
POST /buy	New-key checkout (Stripe)	—
POST /top-up?key={key}	Returning-customer top-up (Stripe)	—

Auth is the x-api-key header. Responses include X-Credits-Remaining and X-Credits-Charged. See agents.md for the full error table and response shapes.

Examples

• examples/podcast_summarizer.py — fetch a transcript and summarize it
• examples/rag_pipeline.py — chunk a transcript for a vector store / RAG
• examples/quickstart.sh — search → transcript in two curl calls
• examples/archive-show.sh — archive a show's entire back catalogue, one file per episode

Use from Python

The spoken-md package wraps the API with no dependencies outside the standard library, and installs a spoken-md command.

pip install spoken-md

from spoken_md import Spoken

spoken = Spoken()                                  # SPOKEN_API_KEY, or the demo key
episode = spoken.search("huberman sleep")[0]
print(spoken.transcript(episode.id))               # Markdown with real speaker names

archive(podcast_id, skip=...) walks a whole show and is resumable; errors are typed by status (PaymentRequired carries the top-up URL, NotFound means no transcript). See python/README.md.

Use as an MCP server

Spoken is a Model Context Protocol server two ways: hosted at https://spoken.md/mcp, and as spoken-mcp, the package in this repo, for clients that run a server locally (Claude Desktop, Cursor, Cline, …). Both provide the same eight tools:

Tool	Description
search_podcasts	Find episodes by text or a pasted Spotify/YouTube URL
list_episodes	List a show's entire back-catalog from a podcast_id
get_transcript	Fetch an episode's transcript as Markdown with real speaker names
get_balance	Check remaining credits
list_following	The shows this key is kept current on, inferred from fetches or declared
follow_podcast	Declare a follow for a show (or clear a mute)
unfollow_podcast	Mute a show so it leaves the list and fetches do not re-add it
list_new_episodes	New episodes on followed shows that have not been fetched yet, with transcript links

Keeping a knowledge base current is list_new_episodes on a schedule and get_transcript on what it lists: each fetch raises that show's floor.

Hosted

Nothing to install. Point a client that connects to a URL at https://spoken.md/mcp (Streamable HTTP):

claude mcp add --transport http spoken https://spoken.md/mcp

The client asks you to sign in the first time a tool needs your key. To skip that, send the key as a header yourself: Authorization: Bearer pt_your_key.

A client that can only sign in with OAuth, such as ChatGPT in developer mode, is sent to a page where you paste your key once. Steps for each app: spoken.md/mcp-server. With no key at all, searching, listing a show and the demo episode work.

Local

Add it to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "spoken": {
      "command": "npx",
      "args": ["-y", "spoken-mcp"],
      "env": { "SPOKEN_API_KEY": "pt_your_key" }
    }
  }
}

SPOKEN_API_KEY defaults to pt_demo (search works fully; transcripts limited to the demo episode). Get a real key at spoken.md.

Run from source instead:

npm install && npm run build
SPOKEN_API_KEY=pt_your_key node dist/index.js

Use with AI agents

Spoken is designed to be called by agents. Point your agent at the Agent Skill (also served at https://spoken.md/.well-known/skills/spoken-md/SKILL.md), or hand it agents.md. The OpenAPI spec makes it easy to wrap as a tool for any function-calling or MCP-compatible client (Claude, GPT, Cursor).

Pricing

Pay-per-use credits, no subscription. New keys: 100 for $15, 500 for $50, 2,000 for $160. Machine-readable at spoken.md/pricing.md.

Links

• Website & docs: https://spoken.md
• Agent instructions: https://spoken.md/agents.md
• OpenAPI spec: https://spoken.md/.well-known/openapi.json
• LLM-friendly overview: https://spoken.md/llms.txt

---

Spoken is built and maintained at spoken.md.