The client says 401 unauthorized

Connecting and listing tools needs no key, so a 401 means a key WAS offered and is wrong, or a tool was called without one. Check that the value starts with “Bearer sk_” and that the key is still active. Revoking a key takes effect immediately.

A tool call returns insufficient_credits

The balance is empty. Tool errors reach the model in the same envelope as REST errors, with a machine-readable code. Top up to continue. The free grant is one-time and isn't renewed. Connecting and listing tools keeps working either way.

The client connects but the model never calls the tools

Most clients enable tools per chat or per agent. Check that the server is switched on in the client settings, then ask something concrete that mentions a video or a channel, and the model picks tools by the task.

Claude Desktop refuses the config

It can't send custom headers natively, so the config goes through the mcp-remote bridge (see the Claude Desktop tab above). Node.js has to be installed, npx downloads the bridge on first run.

GET requests to the URL return 405

Expected. The server is stateless Streamable HTTP, clients POST JSON-RPC messages to the endpoint, and there's no event stream and no session to subscribe to.

The API as tools your agent already knows

The same YouTube transcript, search, channel and playlist endpoints, reachable two ways. As an MCP server any assistant can call mid-conversation, or as drop-in agent skills. One key, the same credits, free plan included.

Overview

The same endpoints as tools for AI assistants.

Every data endpoint is also a Model Context Protocol tool, so Claude, Cursor and other MCP clients can call it mid-conversation. Same key, same credits, free plan included.

POST https://api.transcriptout.com/mcp

Streamable HTTP with stateless JSON-RPC over initialize, tools/list, tools/call and ping. No event stream and no session, so a GET answers 405 by design. Connecting and listing tools works without a key, tool calls need one on every request. A bad key is a plain HTTP 401, not a tool error.

Quick start

From connecting a client to the first result.

1
Add the server
Point your client at the MCP URL below with your key. The Connect section has the exact config for Claude Code, Cursor, Claude Desktop and any other client.
2
Ask in plain language
Say something concrete like get the transcript of this video and summarize it, with a link. The assistant picks the right tool by the task.
3
Nothing else to wire
The same key and credits as REST, and the free plan works here too. Tool calls show up in Logs under their endpoint.

Connect

Same URL everywhere, only the way of passing the key differs.

One command in the terminal, the key travels in a header.

terminal.sh

claude mcp add --transport http youtube-transcripts \
  https://api.transcriptout.com/mcp \
  --header "Authorization: Bearer sk_your_key_here"

Then ask the assistant something concrete, for example “get the transcript of this video and summarize it” with a link. It picks the right tool by the task.

Tools

Fourteen tools, one per endpoint.

Every tool is a thin wrapper over a REST endpoint, so the parameters, the response envelope inside the result and the error codes match. Paid tools cost one credit, the job polling tools and get_credits are free.

Task	Tool
Transcript of one video	get_transcript
Video title, channel and languages	get_video_info
Find videos or channels	search_youtube
A channel's uploads	list_channel_videos
Search within a channel	search_channel_videos
Check a channel for new uploads	latest_channel_videos
Videos in a playlist	list_playlist_videos
Find a video in a playlist	search_playlist_videos
Transcripts for many videos at once	submit_transcripts_job
Remaining credit balance	get_credits

Transcripts

Turn a single video into text or a subtitle file.

get_transcript1 credit

Pulls the transcript of one video from an id or a full URL. Plain text by default, timed segments with format=json, and srt, vtt or raw srv3 when a file is the goal. Set segment to size the pieces, 500 to 1500 works well for retrieval chunks. Add video_metadata=true for the title and channel in the same call.

Parameters

video *: Video id (11 chars) or any YouTube URL.
lang: Track language, en by default. No track in that language answers 404.
kind: manual or auto. Omit to prefer the human track and fall back to auto.
format: json, text, srt, vtt or srv3. Changes only the transcript type.
segment: Max characters per segment, 20 to 5000. Not valid with srv3.
video_metadata: Also return the title, channel and duration.

Returns

The transcript in the chosen format, plus the list of language tracks the video has.

Example

get_transcript(video="https://youtu.be/dQw4w9WgXcQ", format="json", segment=1000)

REST endpoint

get_video_info1 credit

Title, channel, duration, views and available languages of a video, without the subtitles, for when the transcript itself is not wanted.

Parameters

id *: Video id or any YouTube URL.

Returns

Metadata plus the authoritative list of transcript tracks the video has.

Example

get_video_info(id="dQw4w9WgXcQ")

REST endpoint

Search and channels

Find videos and channels, and browse what a channel has.

search_youtube1 credit

Searches YouTube for videos or channels, ranked the way the site ranks them, with pagination.

Parameters

q *: Query, 1 to 200 chars. Optional if you pass next_page_token.
type: video or channel, video by default.
limit: Results per page, 1 to 50.
next_page_token: Token from a previous response.

Returns

A page of video or channel results with a next_page_token.

Example

search_youtube(q="rust tutorial", limit=20)

REST endpoint

list_channel_videos1 credit

Everything on a channel's Videos tab, newest first, paginated. Accepts an @handle, a channel id or a URL.

Parameters

name *: @handle, channel name, UC… id or channel URL.
limit: Page size up to 100, or up to 500 with ids_only.
next_page_token: Token from a previous response.
ids_only: Return video ids instead of full objects.

Returns

A page of the channel's videos, or just video ids with ids_only.

Example

list_channel_videos(name="@Fireship", limit=50)

REST endpoint

search_channel_videos1 credit

YouTube's own relevance search scoped to one channel. Matches titles, descriptions, tags and even spoken words.

Parameters

name *: @handle, channel name, UC… id or channel URL.
q *: Query, 1 to 200 chars.
limit: Results per page, 1 to 100.
next_page_token: Token from a previous response.

Returns

A page of matching videos from that channel.

Example

search_channel_videos(name="@Fireship", q="typescript")

REST endpoint

latest_channel_videos1 credit

The roughly 15 most recent uploads of a channel from its RSS feed, the fastest and lightest way to poll for what is new.

Parameters

name *: @handle, channel name, UC… id or channel URL.

Returns

The newest uploads with ISO timestamps, plus a flat list of their ids.

Example

latest_channel_videos(name="@Fireship")

REST endpoint

Playlists

List a playlist and find a video inside it.

list_playlist_videos1 credit

Videos of a playlist in playlist order, paginated. Accepts a playlist id or any URL that carries a list parameter.

Parameters

id *: PL… playlist id or a URL with a list parameter.
limit: Page size up to 100, or up to 500 with ids_only.
next_page_token: Token from a previous response.
ids_only: Return video ids instead of full objects.

Returns

A page of the playlist's videos, or just video ids with ids_only.

Example

list_playlist_videos(id="PLillGF-RfqbbnEGy3ROiLWk7JMCuSyQtX")

REST endpoint

search_playlist_videos1 credit

Finds videos in a playlist by a substring of the title. YouTube has no native playlist search, so we page through the playlist and filter.

Parameters

id *: PL… playlist id or a URL with a list parameter.
q *: Substring to match in the title, case-insensitive.
limit: Maximum matches to return, 1 to 100.

Returns

Matching videos, with how many items were scanned and whether the scan was truncated.

Example

search_playlist_videos(id="PLillGF-RfqbbnEGy3ROiLWk7JMCuSyQtX", q="async")

REST endpoint

Batch jobs

Queue up to 4,000 videos and read the transcripts as they land.

submit_transcripts_job1 credit per video

Queues up to 4,000 videos at once and returns a job id immediately. Takes the same options as get_transcript, one set for the whole job. Charged on submit and needs a user key.

Parameters

videos *: Video ids or URLs, up to 4,000. Duplicates are collapsed before you are charged.
lang: One language for the whole job.
format: json, text, srt, vtt or srv3, as on get_transcript.
kind: manual or auto, for every video in the job.
segment: Max characters per segment, one size for the whole job.
video_metadata: Add the video metadata to each item.

Returns

A job id, a status and the credits charged.

Example

submit_transcripts_job(videos=["dQw4w9WgXcQ", "kX7Zj9NqGkY"], format="text")

REST endpoint

get_transcripts_jobFree

How far along a batch job is. Ready, failed and still pending. Safe to poll as often as you like.

Parameters

job_id *: The id submit_transcripts_job returned.

Returns

Counts of done, ready, failed and pending, plus the credits charged so far.

Example

get_transcripts_job(job_id="17ef4c30218c47bc98bb5ac072d564e4")

REST endpoint

get_transcripts_resultsFree

The finished transcripts of a batch job, a page at a time, readable while the rest are still running.

Parameters

job_id *: The id submit_transcripts_job returned.
limit: Results per page, 1 to 500.
next_page_token: Token from the previous page.

Returns

A page of results in the order they landed, with a next_page_token.

Example

get_transcripts_results(job_id="17ef4c30218c47bc98bb5ac072d564e4", limit=100)

REST endpoint

get_transcripts_resultFree

One video's result out of a batch job by its id, without paging the whole set.

Parameters

job_id *: The id submit_transcripts_job returned.
video_id *: The video whose result you want.

Returns

The single result for that video, ready or error.

Example

get_transcripts_result(job_id="17ef4c30218c47bc98bb5ac072d564e4", video_id="dQw4w9WgXcQ")

REST endpoint

cancel_transcripts_jobFree

Stops a batch job. Only videos not started yet are refunded, anything already fetched stays in the results and stays charged.

Parameters

job_id *: The id submit_transcripts_job returned.

Returns

The job's final status and the refund.

Example

cancel_transcripts_job(job_id="17ef4c30218c47bc98bb5ac072d564e4")

REST endpoint

Account

Read what the model cannot see in a header.

get_creditsFree

The remaining credit balance on the key. It exists because the X-Credits-Remaining header never reaches the model.

Returns

The remaining credits on the key.

Example

get_credits()

Credits and limits

The same rules as REST, nothing new to learn.

Cost per call

A tool call costs the same credits as the matching REST endpoint, 1 credit by default.

What is free

Connecting, listing tools and pings are free and need no key. So are job polling, results and canceling.

Refunds

Same refund rules as REST. Calls rejected before reaching YouTube are credited back, and so is a 503.

Balance

The balance after each call comes back in the X-Credits-Remaining header.

Logs

Tool calls show up in Logs under their endpoint with method MCP.

Rate limits

Rate limits are shared with the REST API, one pool per key.

Protocol problems come back as a JSON-RPC error, a failed call as isError with our usual envelope inside. MCP is part of every plan, free included. If a key works for REST, it works here.

Troubleshooting

The five things that trip people up.

: Connecting and listing tools needs no key, so a 401 means a key WAS offered and is wrong, or a tool was called without one. Check that the value starts with “Bearer sk_” and that the key is still active. Revoking a key takes effect immediately.
: The balance is empty. Tool errors reach the model in the same envelope as REST errors, with a machine-readable code. Top up to continue. The free grant is one-time and isn't renewed. Connecting and listing tools keeps working either way.
: Most clients enable tools per chat or per agent. Check that the server is switched on in the client settings, then ask something concrete that mentions a video or a channel, and the model picks tools by the task.
: It can't send custom headers natively, so the config goes through the mcp-remote bridge (see the Claude Desktop tab above). Node.js has to be installed, npx downloads the bridge on first run.
: Expected. The server is stateless Streamable HTTP, clients POST JSON-RPC messages to the endpoint, and there's no event stream and no session to subscribe to.

Agent skills

The API as installable knowledge, for agents that read skills.

For agents that read Agent Skills rather than MCP (Claude Code, Cursor, Codex, OpenClaw, Hermes), twelve drop-in skills describe every endpoint with the exact request, its cost and its error recovery. One command installs the full set or a single skill.

terminal.sh

# Claude Code, Cursor, Codex and friends
npx skills add artemchuikin/youtube-skills --skill youtube-full

The source lives on GitHub, and the same skills are published on ClawHub and Smithery under the same names.

In-chat signup

An agent can open the account itself, no browser.

Two requests, an email code between them, an sk_ key at the end. The code arrives in the same email the sign-in page sends, and the account is a regular one.

1
Request a code
One unauthenticated POST with the user's email. A code lands in their inbox, and the response carries a short-lived session token for step two. One request per address per minute.
register.sh
1
2
3
```
curl -X POST "https://api.transcriptout.com/auth/register-cli" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```
2
Trade the code for a key
The session token goes in the Authorization header, the code in the body. Back comes a normal sk_ key for a normal account, with dashboard, free credits and the welcome email included.
verify.sh
1
2
3
4
```
curl -X POST "https://api.transcriptout.com/auth/verify-cli" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"otp":"123456"}'
```

Registration is free and throttled. One code per address per minute and a handful of attempts per code. An existing account is simply signed in, because possession of the emailed code is the same proof the sign-in link relies on.

A tool acting up or a detail out of date? Write to support@transcriptout.com , we keep this page in step with the API.