@thumbapi/mcp-server

MCP server that exposes the ThumbAPI thumbnail generation endpoint as a Model Context Protocol tool. Point any MCP-compatible AI agent at it and ask for a YouTube thumbnail, Instagram post, X/Twitter card, LinkedIn share, or blog hero image from a title.

• Transport: stdio (local, no remote server, no OAuth)
• Runtime: Node.js 18+, installed via npx
• Tool exposed: generate_thumbnail

---

Get your API key

1. Sign up at thumbapi.dev
2. Open the dashboard and copy your API key (it starts with yt_)
3. Use it as the THUMBAPI_API_KEY env var in the configs below

For a smoke test without spending credits you can use the key thumbapi_test, which returns a static placeholder image.

---

Install & configure

Below are configs for the 5 most common MCP clients. Each uses the same command / args / env — only the config file location and JSON wrapper shape change per client.

Claude Desktop

Config file:

• 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"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Config file: ~/.cursor/mcp.json (or per-project .cursor/mcp.json)

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

Reload Cursor's MCP servers from Settings → MCP.

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json

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

Open Windsurf → Settings → Cascade → MCP Servers → Refresh.

Cline (VS Code extension)

Config file:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

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

Open the Cline sidebar → MCP Servers → Restart.

Continue.dev

Config file: ~/.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@thumbapi/mcp-server"],
          "env": {
            "THUMBAPI_API_KEY": "yt_your_key_here"
          }
        }
      }
    ]
  }
}

Reload Continue from the VS Code / JetBrains extension.

---

Tool reference

generate_thumbnail

Generates a thumbnail from a title.

Param	Type	Required	Notes
title	string (1–200 chars)	yes	The headline / video title.
format	youtube | instagram | x | blogpost | linkedin	yes	Target platform / aspect ratio.
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 image content block plus a text summary with generationId.

---

Environment variables

Var	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.

---

Local development

npm install
npm run build
THUMBAPI_API_KEY=thumbapi_test node dist/index.js

The server speaks JSON-RPC over stdio, so it's easiest to test by wiring it into one of the clients above.

License

MIT