ThumbAPI MCP Server — Generate Thumbnails Directly from Your AI Agent

The official @thumbapi/mcp-server exposes ThumbAPI as a native Model Context Protocol tool. Point any MCP-compatible client at it and ask — in plain English — for a YouTube thumbnail, Instagram post, X/Twitter card, LinkedIn share, or blog hero image. No HTTP node, no code, no leaving the agent.

What you get

Transport: stdio — runs locally, no remote server, no OAuth
Runtime: Node.js 18+, invoked via npx — nothing to clone, nothing to build
Tool exposed: generate_thumbnail — returns the generated image inline plus metadata
Auth: single THUMBAPI_API_KEY env var — forwarded as the x-api-key header to api.thumbapi.dev

npm package About MCP

Step 1: Get your API key

Sign up at app.thumbapi.dev (free tier: 50 credits/month, no credit card).
Open the dashboard → API Setup and copy your key. It starts with yt_.
Use it as the value of THUMBAPI_API_KEY in the configs below.

Want to smoke-test first? Use the public test key thumbapi_test instead of a real key. It returns a static placeholder image so you can verify the wiring end-to-end without spending credits — or even creating an account.

{
  "env": {
    "THUMBAPI_API_KEY": "thumbapi_test"
  }
}

Step 2: Install & configure your client

Every client below runs the exact same command — npx -y @thumbapi/mcp-server — with the same env var. Only the config file location and JSON wrapper shape change. Pick your agent and copy the block.

Open your claude_desktop_config.json (create it if it doesn't exist) and add the thumbapi server under mcpServers.

macOS:~/Library/Application Support/Claude/claude_desktop_config.json
Windows:%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thumbapi": {
      "command": "npx",
      "args": ["-y", "@thumbapi/mcp-server"],
      "env": {
        "THUMBAPI_API_KEY": "yt_your_key_here"
      }
    }
  }
}

Fully quit and restart Claude Desktop. The thumbapi server should appear in the tools panel next to the message input.

Step 3: Verify — ask your agent to generate one

Once the server is connected, prompt the agent in plain English. It will call generate_thumbnail with the right parameters and render the returned image inline in the chat.

Use the thumbapi generate_thumbnail tool to create a YouTube thumbnail with the title "How I Ship Features in 30 Minutes".

You should see a 1280×720 WebP thumbnail appear in the reply within a few seconds. The response also includes a generationId you can reference in dashboard logs.

Tool reference: `generate_thumbnail`

Param	Type	Required	Notes
`title`	string (1–200)	yes	Headline / video title, exactly as it should appear.
`format`	enum	yes	`youtube` · `instagram` · `x` · `blogpost` · `linkedin`
`model`	`sd` \| `hd`	no	Default `sd` (10 credits). `hd` needs Pro/Business (20 credits).
`outputFormat`	`webp` \| `png`	no	Default `webp`.
`category`	string	no	Content category hint (e.g. `tech`, `gaming`).

Returns an MCP imagecontent block (so the agent can “see” the result) plus a text summary with generationId.

Environment variables

Variable	Required	Default	Notes
`THUMBAPI_API_KEY`	yes	—	Your `yt_...` key from thumbapi.dev. Use `thumbapi_test` for a placeholder smoke test.
`THUMBAPI_BASE_URL`	no	`https://api.thumbapi.dev`	Override to point at a staging environment.

Troubleshooting

Server shows as disconnected in the client. Confirm node --version reports v18 or newer, and that npx is on your PATH. On macOS, Claude Desktop launches from a login shell that may not see your nvm Node — install Node system-wide (e.g. from nodejs.org) if needed.
401 UNAUTHORIZED from the tool. Your key is missing or wrong. Copy it fresh from the API Setup page and paste it into the env block. Real keys start with yt_.
429 credit / rate limit. Free tier is 50 credits/month. Each sd generation costs 10, each hd costs 20. Upgrade at thumbapi.dev/pricing or wait for the next billing cycle.
The agent won't call the tool.Some clients require you to explicitly enable a server or approve it once per session (Cursor, Windsurf). Check the MCP panel in your client's settings and toggle thumbapi on.