API and MCP

ThumbnailMaker as tools for Claude, Cursor and your own scripts. Three tools are free and need no account. Generating, correcting and making three to test need a key from the Studio plan, and use its thumbnails exactly like the app does.

How do I connect the MCP server?

The server speaks Streamable HTTP at one address. Add it as a remote MCP server in your client; the free tools work with no key.

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

Claude Code

claude mcp add --transport http thumbnailmaker https://www.thumbnailmaker.so/api/mcp \
  --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" }
    }
  }
}

Leave the header out for the free tools only. Claude on the web and ChatGPT add remote servers as connectors without custom headers, so there the free tools work and the Studio tools need a client that can send your key.

Which tools does it have?

Free, no key

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.

Studio key

generate_thumbnailFrom 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_thumbnailOne change by instruction on an existing thumbnail; the rest stays put and the original is kept.
make_three_to_testThree concepts on three angles for YouTube's own A/B test.
list_thumbnailsYour latest thumbnails with their links.
get_accountYour plan and the thumbnails left this month.

How do I call the REST API?

Every endpoint takes JSON and answers JSON, with your key as a bearer token. Images come back as links to the stored files, the same ones your Library shows.

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/account`	Plan and thumbnails left.

A failure answers { "error", "message" } with the status that explains it: 401 for a missing or revoked key, 403 when the account is not on Studio, 402 when the month's thumbnails are used up, 429 when a limit is reached.

What does it cost, and what are the limits?

The API and the MCP tools use the same thumbnails as the app: Studio has 300 a month for $99. One image is one thumbnail, 4K is two, three to test is three. Nothing is counted when a call returns nothing.
60 paid calls per key per hour, and five generations a minute per account. Up to 5 active keys, made and revoked in Settings. A key is shown once.
The free tools are limited per address: the brief to 10 an hour, the check to 30 an hour.
The same rules as the app apply: real people and celebrities are refused, and every image is checked.

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

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