Developers · API Reference

MCP Server

YtBulkTranscript exposes a Model Context Protocol server so agents like Claude, Cursor, and ChatGPT can fetch YouTube transcripts directly as a tool call — no scraping, no copy-pasting URLs into a web form.

Endpoint

/mcp

Transport

Streamable HTTP

Auth

API key

Billing

2 credits / video

You don't have an API key yet — generate one first, it's free.

Get API key

Introduction Authentication Billing & caching get_transcript get_bulk_transcripts Response object Errors Claude Cursor ChatGPT / OpenAI

Introduction

The server exposes two tools — get_transcript for a single video and get_bulk_transcripts for a list of URLs, a playlist, or an entire channel. Both return the same response shape, so your agent only needs to understand one schema.

Jump straight to client setup for copy-paste configuration, or keep reading for the full tool and authentication reference.

Authentication

Every request is authenticated with your personal API key, found on your account page. The server accepts the key in three ways, checked in this order:

Method	How	When to use
Header	`X-Api-Key: <your-key>`	Preferred — use whenever your client lets you set custom headers.
Bearer token	`Authorization: Bearer <your-key>`	Equivalent to the header method, for clients that only expose a bearer-token field.
Path	`/mcp/<your-key>`	Fallback for connector dialogs (Claude, ChatGPT) that offer no header field at all.

A request with no key, or an unrecognized one, fails with Not authenticated.

Billing & caching

•MCP/API calls are billed at 2 credits per video — double the web rate. The same credit packs cover both.
•Credits for a bulk request are charged upfront for the full video count; any video that fails is automatically refunded.
•Calling either tool again for the same set of videos within 48 hours returns the cached result with "cached": true and 0 credits charged — no re-fetch, no re-charge.
•The cache is keyed by your account and the resolved set of video IDs, not by which tool or parameter produced them — so a single-video call and a bulk call for that same video share one cache entry.

See the pricing page for credit pack sizes and prices.

get_transcript

2 credits

Fetches the transcript for a single YouTube video. Fails outright (rather than returning an empty success) if the video can't be transcribed at all — so your agent can react to a real error instead of parsing an empty list.

Parameters

Name	Type	Required	Description
videoUrl	string	Yes	A YouTube video URL or bare video ID.

Example

Request

{
  "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

Response

{
  "status": "done",
  "cached": false,
  "transcripts": [
    {
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "fullText": "We're no strangers to love..."
    }
  ],
  "succeededCount": 1,
  "creditsCharged": 2
}

get_bulk_transcripts

2 credits / video

Fetches transcripts for many videos at once — a list of URLs, a playlist, or an entire channel. Provide exactly one of videoUrls, playlistUrl, or channelUrl. Up to 2,000 videos per call.

Inline vs. background job

•10 or fewer videos — resolved synchronously; transcripts come back directly in the response (status: "done").
•More than 10 videos — dispatched as a background job; the call returns immediately with status: "processing". Call the tool again with the same arguments to poll progress or retrieve the finished result. Results are also emailed as a ZIP once done.

Parameters

Name	Type	Required	Description
videoUrls	string[]	One of three	A list of YouTube video URLs or IDs.
playlistUrl	string	One of three	A YouTube playlist URL.
channelUrl	string	One of three	A YouTube channel URL or @handle.

Example — 12 videos (background job)

Request

{
  "channelUrl": "https://www.youtube.com/@somechannel"
}

Response — job started

{
  "status": "processing",
  "videoCount": 150,
  "creditsCharged": 300,
  "estimatedSecondsRemaining": 420,
  "message": "Call this tool again with the same videos to check progress or retrieve results."
}

Polling — call again with the same channelUrl while it's still running

{
  "status": "processing",
  "processedCount": 60,
  "totalCount": 150,
  "estimatedSecondsRemaining": 180
}

Response object

Both tools return the same shape. Fields not relevant to a given response (e.g. transcripts while a job is still processing) are omitted rather than sent as null.

Field	Type	Present when
status	string	Always. `"done"` or `"processing"`.
cached	boolean	When `status` is `"done"`. True if served from the 48h cache at 0 credits.
transcripts	array	When `status` is `"done"`. Each entry: `videoId`, `title`, `fullText`.
succeededCount	number	When `status` is `"done"`.
failedCount	number	Bulk requests only, when not served from cache.
sampledErrors	string[]	Bulk requests with failures. Up to 5 sample `"videoId: reason"` entries.
creditsCharged	number	Almost always. 0 for cache hits; failed videos in a bulk request are excluded/refunded.
processedCount	number	When polling a job that's still `"processing"`.
totalCount	number	When polling a job that's still `"processing"`.
videoCount	number	Right after a new background job is created.
estimatedSecondsRemaining	number	While `status` is `"processing"`.
message	string	Occasional human-readable hint, e.g. how to poll a job.

Errors

Failures are returned as standard MCP tool errors with one of the messages below.

Message	Cause
Not authenticated.	No API key, or an unrecognized one, was sent with the request.
Invalid YouTube URL or video ID.	`videoUrl` in `get_transcript` couldn't be parsed.
Could not fetch the transcript. The video may be private, unavailable, or have no captions.	`get_transcript` resolved the video but couldn't produce a transcript.
Provide exactly one of videoUrls, playlistUrl, or channelUrl — not multiple.	More than one source parameter was set on `get_bulk_transcripts`.
Provide videoUrls, playlistUrl, or channelUrl.	No source parameter was set on `get_bulk_transcripts`.
No valid videos found.	The resolved playlist/channel/list contained zero usable video IDs.
Insufficient credits. Balance: X, required: Y (N videos x 2).	Your credit balance doesn't cover the request. Top up at `/account`.

Client setup

Pick your client and follow the steps.

1. Open the connector settings

In Claude, click your profile icon → Settings → Customize → Connectors. Scroll to the bottom and click Add custom connector.

2. Fill in the dialog

A dialog opens with a Name field and a Remote MCP Server URL field. Leave Advanced settings (OAuth Client ID / Client Secret) empty — you don't need them.

Name

YtBulkTranscript

Remote MCP Server URL

https://ytbulktranscript.app/mcp/<your-key>

The dialog has no field for auth headers, so your API key is embedded directly in the URL — that's what the /mcp/<key> path is for.

3. Connect & ask

Click Add, then Connect. Start a new chat and ask "Get the transcript of <video URL>" — Claude calls the tool directly.

1. Open your MCP config

Project-only: create .cursor/mcp.json in your repo.
All projects: edit ~/.cursor/mcp.json.

2. Add this server entry

Cursor's HTTP/SSE servers support a proper auth header, so use that instead of embedding the key in the URL.

{
  "mcpServers": {
    "yt-bulk-transcript": {
      "url": "https://ytbulktranscript.app/mcp",
      "headers": { "X-Api-Key": "<your-key>" }
    }
  }
}

3. Reload & ask

Reload the window, then ask the agent to fetch a transcript — it'll show up as an available tool call.

Prefer the Settings UI instead?

Cursor Settings → MCP → "+ Add new MCP Server" opens a dialog with Name, Transport Type, and Command or URL — but no header field. Set Transport Type to streamable-http and, since there's nowhere to put the header, use https://ytbulktranscript.app/mcp/<your-key> as the URL instead.

1. Turn on Developer mode

Settings → Apps & Connectors → Advanced settings → toggle Developer mode on. Available on Plus, Pro, Business, Enterprise, and Education plans (web). You'll see a warning that custom connectors run third-party code — that's expected.

2. Create the connector

Go to Settings → Connectors → Create. Fill in:

Connector name

YtBulkTranscript

Server URL

https://ytbulktranscript.app/mcp/<your-key>

Authentication

No authentication

The dialog only offers OAuth or no authentication — no header field — so the API key goes in the URL itself instead. Check "I trust this application" and click Create.

3. Enable it in chat & ask

In a new chat, open the tools/connectors menu, enable YtBulkTranscript, then ask "Get the transcript of <video URL>".

Building your own agent instead?

If you're integrating against the OpenAI Agents SDK or Responses API directly, you can connect to this server (and use a real auth header) like this:

from openai import OpenAI
client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",
    input="Get the transcript of https://youtube.com/watch?v=...",
    tools=[{
        "type": "mcp",
        "server_url": "https://ytbulktranscript.app/mcp",
        "headers": { "X-Api-Key": "<your-key>" }
    }]
)

MCP calls are billed at 2× the normal credit rate (single video: 2 credits). See pricing

MCP Server

Introduction

Authentication

Billing & caching

get_transcript

Parameters

Example

get_bulk_transcripts

Inline vs. background job

Parameters

Example — 12 videos (background job)

Response object

Errors

Client setup

1. Open the connector settings

2. Fill in the dialog

3. Connect & ask

1. Open your MCP config

2. Add this server entry

3. Reload & ask

Prefer the Settings UI instead?

1. Turn on Developer mode

2. Create the connector

3. Enable it in chat & ask

Building your own agent instead?

Sign In