YouTube thumbnail API and MCP

ThumbnailMaker as tools for Claude Code, Cursor, VS Code and your own scripts. To use it from ChatGPT or Claude in the browser, follow the three steps for chat apps.

How do I connect the MCP server?

Streamable HTTP, stateless. One address for everything once you are signed in, one for the three free tools with no account at all.

Signed in, every tool

OAuth (the client opens a ThumbnailMaker login, you click Allow) or a Studio key as a bearer token.

No account, free tools

The brief, the check and the specs, limited per address.

https://www.thumbnailmaker.so/api/mcp

https://www.thumbnailmaker.so/api/mcp/free

Claude Code

claude mcp add --transport http thumbnailmaker https://www.thumbnailmaker.so/api/mcp
# then /mcp in Claude Code to log in, or send a key:
#   --header "Authorization: Bearer tm_your_key"

Cursor, VS Code, Claude Desktop

{
  "mcpServers": {
    "thumbnailmaker": {
      "url": "https://www.thumbnailmaker.so/api/mcp",
      "headers": { "Authorization": "Bearer tm_your_key" }
    }
  }
}

A request with no credentials gets a 401 whose WWW-Authenticate header points at /.well-known/oauth-protected-resource; clients that speak MCP authorization start the login from there.

Which tools does it have?

Free

write_thumbnail_briefA YouTube link in, the brief out: one scene with a single focal point, two to four words for the image, the style that fits, and a link that opens the generator on it.
check_thumbnailMeasures a video's current thumbnail without AI: whether a 1280-wide custom version exists, whether the duration-badge corner is clear, whether the contrast holds at feed size.
thumbnail_specsYouTube's own sizes, shapes and file limits for videos, Shorts and podcasts, and four design rules that hold at feed size.

Signed in

generate_thumbnailStudioFrom a description or a video link. Style, words on the image, 16:9 or Shorts, 2K or 4K, one or two takes, your brand kit.
correct_thumbnailStudioOne change by instruction on an existing thumbnail; the rest stays put and the original is kept.
make_three_to_testStudioThree concepts on three angles for YouTube's own A/B test.
list_thumbnailsAny planYour latest thumbnails with their links.
get_thumbnailAny planOne thumbnail by id, as an image.
list_brand_kitsAny planYour brand kits, for brandKitId.
get_accountAny planYour plan and the thumbnails left this month.

The three tools that spend credits never do on the first call: they answer with the price, the balance and a quoteId. Call again with the same arguments, confirm: true and that quoteId (valid 10 minutes) once the person has agreed; a confirmed call without a matching quote answers quote_required, and a quote pays for one call only: sent again, it answers quote_used and charges nothing. Errors come back as tool results with isError and a code from the table below. A tool that returns thumbnails sends the JSON, then for each a preview as image content (1024 px) and a resource_link to the full file.

How do I call the REST API?

Every endpoint takes JSON and answers JSON, with a Studio key as a bearer token, the brief and the check included (they are free over MCP, not over REST). Images come back as links to the stored files, the same ones your Library shows. The whole API is described in an OpenAPI 3.1 spec.

curl https://www.thumbnailmaker.so/api/v1/thumbnails \
  -H "Authorization: Bearer tm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"videoUrl": "https://www.youtube.com/watch?v=...", "format": "16:9"}'

REST API endpoints
Endpoint	What it does
`POST /api/v1/thumbnails`	Generate. Body: prompt or videoUrl, then text, style, format, resolution, takes, brandKitId, matchVideoLook.
`GET /api/v1/thumbnails`	Your latest thumbnails. ?limit= up to 50.
`GET /api/v1/thumbnails/{id}`	One thumbnail.
`POST /api/v1/thumbnails/{id}/corrections`	A correction. Body: instruction.
`POST /api/v1/packs`	Three to test. Body: prompt or videoUrl, then text, style, format, brandKitId.
`POST /api/v1/briefs`	The brief for a video. Body: videoUrl.
`POST /api/v1/checks`	The check of a video's thumbnail. Body: videoUrl.
`GET /api/v1/brand-kits`	Your brand kits (id, name), for brandKitId.
`GET /api/v1/account`	Plan and thumbnails left.

A thumbnail, wherever one comes back:

{
  "id": "uuid",
  "url": "https://.../thumbnails/....jpg",
  "format": "16:9",            // or "9:16"
  "prompt": "the brief it was made from",
  "createdAt": "2026-10-24T10:00:00Z",
  "angle": "reaction",         // set on three-to-test concepts
  "qualityScore": 4.5          // feed-size grade, 1 to 5; null when not graded
}

Generate and three to test answer { thumbnails, thumbnailsUsed, thumbnailsLeft } (generate adds brief when it wrote one from the video), a correction { thumbnail, thumbnailsUsed, thumbnailsLeft }. Balances are counted in thumbnails; one thumbnail is 10 credits.

What do the errors mean?

A failure answers { "error", "message", "docs" } with the status that explains it. The message is written for a person and can be shown as is; docs links to this table.

Error codes
Status	error	When
400	`invalid_json`	The body is not a JSON object.
400	`invalid_request`	A field is missing, too long or not one of its values (unknown style, "4K" instead of "4k"). The message names the field.
400	`invalid_url, missing_prompt`	The link is not a YouTube video, or neither prompt nor videoUrl was sent.
400	`identity_not_allowed, person_image`	A real person or celebrity was asked for, or the image to correct is a photo of a person.
401	`invalid_api_key`	The key is missing, malformed or revoked.
402	`insufficient_credits`	The month's thumbnails are used up. The message says how many are left.
403	`plan_upgrade_required`	The account is not on Studio.
404	`not_found, video_not_found, thumbnail_not_found`	Unknown id, a private or deleted video, or a video with no thumbnail.
429	`rate_limited`	An hourly or per-minute limit was reached. Retry later.
500	`server_error`	Something failed on our side. Credits for anything not delivered are refunded.
502	`model_failed, brief_failed, pack_failed`	The model returned nothing usable. Nothing is charged.
503	`model_unavailable`	The image model is down. Retry with backoff.
MCP	`quote_required, quote_used, sign_in_required`	A spending tool was confirmed without its quoteId, or with one an earlier call already used (nothing is charged again), or a signed-in tool was called anonymously.

What does it cost, and what are the limits?

The same credits as the app: Studio has 3000 a month for $99. One image is 10 credits, 4K or a second take adds 10, three to test is 30. A concept or a take that fails is refunded, and so is an image that could not be stored.
60 calls an hour per key: every REST call counts, and over MCP the paid ones (also 60 per OAuth connection). Five generations a minute per account. Up to 5 active keys, made and revoked in Settings. A key is shown once.
The free tools, per address with no account or per account when signed in: the brief 10 an hour and 30 a day, the check 30 an hour and 200 a day.
A call has 60 seconds. When the main image model runs late, a faster one finishes the image.
The same rules as the app: real people and celebrities are refused, and every image is checked.

See the Studio plan or write to contact@thumbnailmaker.so about higher volumes.

Not a developer? Use ThumbnailMaker inside ChatGPT or Claude

For agents: this page in Markdown, the OpenAPI spec and the whole site in one file.

Claude is a trademark of Anthropic and ChatGPT a trademark of OpenAI; ThumbnailMaker is not affiliated with either.