Bannerbear MCP Server & CLI

A free, open source Bannerbear MCP server and CLI that lets Claude Code, Codex, Cursor and other AI agents make images, animations and videos from your templates.

Navid Moazzezby Navid Moazzez·Updated Oct 5, 2026·15 min read·
Your computer
  1. 1

    Add it with a single command in a terminal.

    Put your own V5 API key in place of the example.

    claude mcp add bannerbear \
    -e BANNERBEAR_API_KEY=YOUR_V5_API_KEY \
    -- npx -y @thenavidm/bannerbear-mcp-cli@latest
  2. 2

    In Claude Code, type /mcp. Bannerbear should show as connected.

    /mcp

Needs Node 22 or newer and a Bannerbear V5 API key. Make one in a minute.

It's free and open source. If it saves you time, star it on GitHub, so more people find it.

Rate this tool

This free Bannerbear MCP server and CLI gives your AI real access to your Bannerbear workspace: image and animation templates, renders, workflows, media tools and assets. It fills your templates with new text and pictures, makes images, animations and batches, runs workflows and media tools, and follows each job until it's done.

It's one install with two ways in. Claude, Codex, Cursor or any other MCP app calls its 75 tools for you, and the same tools work as a CLI that agents like Claude Code, Codex and OpenCode run, or that you type yourself.

In this guide, I'll show you:

  • What the Bannerbear MCP server & CLI is, and what you can ask it
  • How to install it and check that it works
  • When to use the MCP server, and when the CLI
  • Every tool, and how to keep your account safe

Every tool on this page comes from the server itself, and every cost was measured in Claude Code.

key_takeaways.mdTL;DR

Key takeaways

It gives Claude, Codex, Cursor and any other MCP app 75 tools for Bannerbear: images and animations from your templates, batches, workflows, media tools like background removal and subtitles, and your assets.
It uses a V5 API key that you can limit to the parts of your workspace you pick.
Every render, upload, edit and delete waits for your approval, because renders spend credits.
The same tools run as a CLI, which costs your AI nothing until it runs.

What is the Bannerbear MCP server & CLI?

The Bannerbear MCP server & CLI is a free, open source program that lets AI agents make images and videos in your Bannerbear workspace for you, in two ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Bannerbear's own API.

The CLI is the same program as commands. bannerbear-cli list-image-templates runs the same code your AI runs when you ask which templates you have, whether an agent like Claude Code runs it or you do.

In an AI OS, the layer that connects your AI to your context, your data and your tools, a server like this is how your AI reaches Bannerbear. I explain how the parts fit together in how to build an AI operating system, and here's how I use AI myself.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Which image templates do I have, and what layers does each one have?
Make my quote card template say "Done is better than perfect", as a PNG.
Make 20 product cards from this list of names and prices.
Remove the background from this photo.
Add subtitles to my latest video.
Is my batch done yet? Send me the links.

The third one shows why this is useful. Your AI turns a list into a batch of finished images in one request, and you approve it before any credits are spent.

It works well next to my Brandfetch MCP server and Creatomate MCP server, so your AI can pull any brand's logo from Brandfetch and make videos from templates with Creatomate in the same chat. Every server I've made is on my MCP servers page.

For the images themselves, my free post image generator and social media image resizer help too.

How to install the Bannerbear MCP server

Pick your app in the box at the top of this page. Each one is a single command or a pasted block, and they all run through npx, so there's nothing to install first.

Windsurf, Zed and Cline take the same server, though they don't have a tab in the box yet. Follow the box's Cursor tab, and put its block here instead:

AppWhere the block goes
WindsurfIn the Cascade panel, open the Actions menu (…) and choose Open MCP config file, then paste the block.
ClineClick the MCP Servers icon in the Cline panel, open the Configure tab, click Configure MCP Servers, and paste the block.
ZedGo to Settings, then AI, then MCP Servers, and choose Add Server, then Add Local Server. Enter the block's command, arguments and variables, and Zed saves them under context_servers.
Before you start0/3

Watch out: Use a V5 API key. Keys from Bannerbear's older V2 API don't work with V5, and the server uses V5.

Set up your Bannerbear account

It takes a minute.

Create a V5 API key0/4

Scopes come in read and write pairs, like images:read and images:write, and a key with no scopes has full access. The same page deletes a key or rolls it to a new one.

A key reaches one workspace, so make one in each workspace you want to connect.

To keep the key out of your app's config, save it alone in a file only you can read, and point BANNERBEAR_TOKEN_FILE at that file's full path instead.

Check that it works

Run the doctor with --network. It checks your settings, then reads your account, which shows the key's scopes and the credits you've used this month. It never renders anything.

npx -y @thenavidm/bannerbear-mcp-cli doctor --network

When every line has a check mark, restart your app and ask it which templates you have. A 403 on a tool means the key lacks that scope.

In Claude Code, /mcp also shows whether the Bannerbear server is connected. It's one of the Claude Code commands worth knowing.

Use the Bannerbear CLI

The CLI is the same 75 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_image_templates runs as bannerbear-cli list-image-templates.

npm install -g @thenavidm/bannerbear-mcp-cli
bannerbear-cli
bannerbear-cli get-account
bannerbear-cli list-image-templates --page 1
bannerbear-cli create-image --payload-file ~/bannerbear/quote-card.json --confirm
bannerbear-cli poll-job --resource images --uid YOUR_IMAGE_UID --max-polls 3

The bare bannerbear-cli lists every command, bannerbear-cli which <words> finds the command for a task, and bannerbear-cli <command> --help shows what a command takes. Every render, upload, edit and delete needs --confirm, the terminal's version of your approval.

bannerbear-cli install <app> adds the server to Claude Code, Codex, Claude Desktop, Cursor, VS Code or Gemini CLI, in each app's own format.

These are the flags you'll use most:

FlagWhat it does
--jsonPrints JSON
--compactPrints the JSON on one line
--select a,b.cKeeps only those fields, and a dotted path goes deeper
--agentMachine mode: compact JSON, no prompts, and it never confirms anything
--confirmLets a write that asks first go ahead
--dry-runShows what a write would do, without doing it

A script can branch on the exit code:

Exit codeWhat it means
0It worked
1Something unexpected went wrong
2The command was typed wrong, or a write needed --confirm
3It wasn't found
4Bannerbear rejected the credentials
5Bannerbear failed or couldn't be reached
7You hit a rate limit, so wait and try again
10Nothing is set up yet

MCP server or CLI: which one?

Both are the same program with the same 75 tools. The difference is when your AI pays for them, in the tokens it reads.

Every message, in an app that loads every tool
MCP server
216,300 tokens
CLI
Nothing
Every message, in Claude Code
MCP server
1,100 tokens
CLI
Nothing
When Bannerbear comes up
MCP server
Nothing more, or in Claude Code the tools it picks
CLI
3,300 tokens, once
20 messages with Bannerbear in one, every tool loaded
MCP server
4,326,000 tokens
CLI
3,300 tokens
Works in Claude Desktop's chat
MCP server
Yes
CLI
No, there's no terminal there
Works in a script, a cron job or CI
MCP server
No
CLI
Yes

An app that loads every tool up front sends the full list with every message, whether you mention Bannerbear or not. Claude Code doesn't by default: its tool search sends only the tool names and the server's instructions, and loads a tool's full definition when your AI reaches for it.

The CLI costs nothing until Bannerbear comes up. Then your agent reads its skill file once and runs the commands it needs. With the skill added, Claude Code also lists its one-line description with every message, about 60 tokens.

When the whole conversation is about Bannerbear, the gap closes. Then the MCP server is the better experience, because you ask in plain language and your AI never has to look up a command.

How to spend less

In Claude Code, leave tool search on, which it is unless you've set ENABLE_TOOL_SEARCH=false.

Turn the server off when you aren't making images. In Claude Code that's the /mcp panel, and every AI app has its own switch. BANNERBEAR_READ_ONLY=1 cuts it to the 33 reading tools.

Or install the CLI and connect the server later, on the days it earns its place. Every tool stays in reach, and the standing cost drops to nothing.

Every number here was measured on October 5, 2026 in Claude Code 2.1.286 with Claude Opus 5.5. It's the same one-line prompt with and without the server connected, once with tool search off so every tool loads, and once with Claude Code's default. The skill was measured the same way, and other apps and models count tokens a little differently.

Templates, jobs and batches

Your AI reads a template first, so it uses the real layer names when it fills in your text and pictures. In V5, those changes go in an object with a list of layers, and the old V2 format doesn't work.

Every render is a job. It comes back with an ID right away, and poll_job checks that same job up to 20 times until it's done, without starting a new one. Bannerbear can also call a webhook when a job finishes.

create_batch makes up to 100 images in one request, though each image still costs its credits. preview_render_batch checks the batch on your computer and gives it a fingerprint, and apply_render_batch sends it only with that fingerprint.

A workflow chains steps, like render then resize, and each step spends its own credits. Media tools, from background removal to subtitles and video trimming, run as jobs the same way.

Webhook and instant URL signing keys work like passwords, so the server saves them to a new private file instead of showing them in chat.

Watch out: Bannerbear allows 60 POST requests every 10 seconds. A template its owner locked against API changes refuses edits, and only the owner can unlock it.

Every Bannerbear tool

The tables below list all 75 tools, grouped by what they're for. Of these, 33 only read, and 42 spend credits or change something in your Bannerbear workspace or on your computer.

Image templates and images

list_image_templates
What it does
Lists your image templates.
Kind
Reads
create_image_template
What it does
Makes an image template.
Kind
Asks first
get_image_template
What it does
Reads one image template, with every layer.
Kind
Reads
update_image_template
What it does
Changes an image template.
Kind
Asks first
delete_image_template
What it does
Deletes an image template.
Kind
Asks first
list_images
What it does
Lists the images you've made.
Kind
Reads
create_image
What it does
Makes an image from a template, with your text and pictures in its layers.
Kind
Asks first
get_image
What it does
Reads one image, and its link once it's done.
Kind
Reads

Batches

list_batches
What it does
Lists your batches.
Kind
Reads
create_batch
What it does
Makes up to 100 images in one request.
Kind
Asks first
get_batch
What it does
Reads one batch and its images.
Kind
Reads
preview_render_batch
What it does
Checks up to 100 images on your computer and gives the batch a fingerprint.
Kind
Reads
apply_render_batch
What it does
Sends a checked batch, only with the fingerprint from its preview.
Kind
Asks first

Animations

list_animations
What it does
Lists the animations you've made.
Kind
Reads
create_animation
What it does
Makes an animation from an animation template.
Kind
Asks first
get_animation
What it does
Reads one animation, and its link once it's done.
Kind
Reads
list_animation_templates
What it does
Lists your animation templates.
Kind
Reads
create_animation_template
What it does
Makes an animation template.
Kind
Asks first
get_animation_template
What it does
Reads one animation template, with its keyframes.
Kind
Reads
update_animation_template
What it does
Changes an animation template.
Kind
Asks first
delete_animation_template
What it does
Deletes an animation template.
Kind
Asks first
animate_template
What it does
Applies an animation preset to an animation template.
Kind
Asks first

Media tools

remove_bg
What it does
Removes an image's background.
Kind
Asks first
generate_ai_image
What it does
Makes an image with the AI model you pick.
Kind
Asks first
generate_ai_video
What it does
Makes a video with the AI model you pick.
Kind
Asks first
video_thumbnails
What it does
Pulls thumbnails from a video.
Kind
Asks first
subtitle_video
What it does
Adds subtitles to a video.
Kind
Asks first
generate_voiceover
What it does
Makes a voice-over from text.
Kind
Asks first
create_pdf
What it does
Makes a PDF.
Kind
Asks first
trim_video
What it does
Trims a video.
Kind
Asks first
concat_videos
What it does
Joins videos into one.
Kind
Asks first
resize_video
What it does
Resizes a video.
Kind
Asks first
crop_video
What it does
Crops a video.
Kind
Asks first
overlay_video
What it does
Lays one video over another.
Kind
Asks first
overlay_image
What it does
Lays an image over a video.
Kind
Asks first
add_audio
What it does
Adds an audio track to a video.
Kind
Asks first
add_cover_art
What it does
Adds cover art to a media file.
Kind
Asks first
create_video_slideshow
What it does
Makes a video slideshow from images.
Kind
Asks first
apply_color_filter
What it does
Applies a color filter to a video.
Kind
Asks first
soften_video
What it does
Softens a video's look.
Kind
Asks first
create_gif_preview
What it does
Makes a GIF preview of a video.
Kind
Asks first
list_tool_jobs
What it does
Lists your media tool jobs.
Kind
Reads
get_tool_job
What it does
Reads one media tool job, and its file once it's done.
Kind
Reads

Workflows

list_workflows
What it does
Lists your workflows.
Kind
Reads
create_workflow
What it does
Makes a workflow, a chain of steps like render then resize.
Kind
Asks first
update_workflow
What it does
Changes a workflow.
Kind
Asks first
delete_workflow
What it does
Deletes a workflow.
Kind
Asks first
get_workflow
What it does
Reads one workflow, with its inputs and steps.
Kind
Reads
list_workflow_runs
What it does
Lists your workflow runs.
Kind
Reads
run_workflow
What it does
Runs a workflow once, which spends credits for each step.
Kind
Asks first
get_workflow_run
What it does
Reads one workflow run, step by step.
Kind
Reads

Assets and template library

list_assets
What it does
Lists the files in your workspace.
Kind
Reads
upload_asset
What it does
Uploads a file from your computer, up to 5 MB.
Kind
Asks first
get_asset
What it does
Reads one file's details.
Kind
Reads
check_assets
What it does
Checks whether files are already in your workspace.
Kind
Reads
list_publications
What it does
Lists ready-made templates you can install.
Kind
Reads
get_publication
What it does
Reads one ready-made template.
Kind
Reads
install_publication
What it does
Copies a ready-made template into your workspace.
Kind
Asks first

Instant URLs and webhooks

list_webhooks
What it does
Lists your webhooks.
Kind
Reads
create_webhook
What it does
Adds a webhook, with its signing key saved to a private file.
Kind
Asks first
get_webhook
What it does
Reads one webhook.
Kind
Reads
update_webhook
What it does
Changes a webhook.
Kind
Asks first
delete_webhook
What it does
Deletes a webhook.
Kind
Asks first
list_instant_urls
What it does
Lists your instant URLs, links that make an image when someone opens them.
Kind
Reads
create_instant_url
What it does
Makes an instant URL, with its signing key saved to a private file.
Kind
Asks first
get_instant_url
What it does
Reads one instant URL.
Kind
Reads
update_instant_url
What it does
Changes an instant URL.
Kind
Asks first
delete_instant_url
What it does
Deletes an instant URL.
Kind
Asks first

Your account and jobs

get_account
What it does
Reads your workspace's plan, the credits you've used and the key's scopes.
Kind
Reads
list_accounts
What it does
Lists the workspaces you've set up, without their keys.
Kind
Reads
get_operation_schema
What it does
Shows every field one of these requests takes.
Kind
Reads
get_layer_schema
What it does
Shows every field a template layer or keyframe can take.
Kind
Reads
preview_operation
What it does
Checks a request on your computer, before anything goes to Bannerbear.
Kind
Reads
query_pages
What it does
Reads up to five pages of a list at once.
Kind
Reads
poll_job
What it does
Checks a running job up to 20 times until it's done, without starting a new one.
Kind
Reads

Is the Bannerbear MCP server safe?

Renders spend credits, and a deleted template is gone. So 42 tools ask first: every render, batch, workflow run, media tool, upload, template change and delete. They're the ones marked "Asks first" in the tool tables above.

Reading templates, jobs and your account never asks, because it costs and changes nothing.

When your AI calls one of them, the call needs a yes first. Where you use it decides who gives it:

  • Claude Code (2.1.246 and later) asks you before every call, in every one of its permission modes.
  • An app that can show forms asks you in a form.
  • Any other app takes your AI's confirm: true as the yes, so tell your AI to check with you first.
  • An agent with no person to ask needs BANNERBEAR_CONFIRM=model, so its confirm: true counts in every app.
  • In a terminal, you add --confirm to the command.

If the answer is no, nothing reaches Bannerbear.

Make it read-only

Set BANNERBEAR_READ_ONLY=1 and every tool that asks first disappears from the tool list, leaving 33 reading tools. A key with only read scopes does the same at Bannerbear's end.

Keep a log of every write

Set BANNERBEAR_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked, with what it was about to do and who approved it.

Watch out: Template text and asset names can come from other people, and one can try to give your AI orders. Treat them as data, and use BANNERBEAR_READ_ONLY=1 for an agent working on its own.

Your data

Your requests go straight to Bannerbear, with no server of ours in between and no tracking. Your key stays in your app's config, your shell or your token file.

An upload sends only the one file you pick, up to 5 MB. The server never downloads your renders, so save the ones you keep from their links.

To cut access, delete or roll the key on the V5 API Keys page, and remove the server from your app's config.

Connect more than one Bannerbear workspace

Each key reaches one workspace, so each workspace is its own account here. Set BANNERBEAR_ACCOUNTS to a JSON list with a name and a key, or a token file, for each workspace, and BANNERBEAR_DEFAULT_ACCOUNT to the one that acts when a tool names none. Every tool takes an optional account.

A workspace never borrows another one's key. If the workspace you name has no key, the call stops instead of rendering in a different workspace.

Bannerbear MCP server settings

Every setting is an environment variable, in your app's config or your shell.

BANNERBEAR_API_KEY
Default
none
What it does
Holds your V5 API key
BANNERBEAR_TOKEN_FILE
Default
none
What it does
Points at a private file holding the key, instead
BANNERBEAR_ACCOUNTS
Default
none
What it does
Lists several workspaces, as JSON
BANNERBEAR_DEFAULT_ACCOUNT
Default
the first one
What it does
Picks the workspace that acts when a tool names none
BANNERBEAR_REQUEST_TIMEOUT_MS
Default
30000
What it does
Gives up on a Bannerbear request after this many milliseconds
BANNERBEAR_MIN_REQUEST_INTERVAL_MS
Default
200
What it does
Waits this many milliseconds between requests
BANNERBEAR_READ_ONLY
Default
off
What it does
1 hides every tool that spends credits or changes something
BANNERBEAR_ALLOW_DESTRUCTIVE
Default
on
What it does
0 refuses the tools that ask first
BANNERBEAR_AUDIT_LOG
Default
none
What it does
Names a file that gets one line per attempted write
BANNERBEAR_SURFACE
Default
full
What it does
search lists three tools that find, describe and run the rest
BANNERBEAR_TOOL_TIMEOUT_MS
Default
none
What it does
Gives up on any tool after this many milliseconds
BANNERBEAR_CONFIRM
Default
human
What it does
model lets your AI's confirm: true approve on its own, for an agent with no person to ask
BANNERBEAR_HTTP_PORT
Default
8787
What it does
Sets the port for --http
BANNERBEAR_HTTP_HOST
Default
127.0.0.1
What it does
Sets the address for --http, and any other needs a token
BANNERBEAR_HTTP_TOKEN
Default
none
What it does
Sets the bearer token every --http request needs
BANNERBEAR_HTTP_ALLOWED_ORIGINS
Default
none
What it does
Lists other websites allowed to call --http, comma separated
BANNERBEAR_DEBUG
Default
off
What it does
1 prints debug lines

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

What you seeWhat to do
A 401 errorThe key is a V2 key, or it was deleted. Make a V5 key on the V5 API Keys page
A 402 errorYou're out of credits for this month. Trying again won't help until they're topped up or reset
A 403 errorThe key lacks the scope for that tool, like images:write
A 423 errorThe template is locked against API changes. Only its owner can unlock it
A job is still pendingCheck the same job again with poll_job, or use a webhook. Never start a new one to check
A V2-style change is refusedV5 takes changes as an object with a list of layers. Read the template's layers first
"…so it will not run without confirm: true"That's the safety check working. Approve it when your app asks

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

More free tools for images and video

Make videos from templates in Creatomate, or pull any brand's logo and colors from Brandfetch.

FAQs about the Bannerbear MCP server & CLI

Here are the questions people ask most about the Bannerbear MCP server and CLI.

The Bannerbear MCP server & CLI is a free, open source program that lets an AI app like Claude, Codex or Cursor make images and videos in your Bannerbear workspace.

It has 75 tools for templates, images, animations, batches, workflows, media tools and assets, and the same tools run as a CLI that agents like Claude Code and Codex use, or that you type yourself.

An MCP server is a standard way to give an AI app real access to a tool, so it can act instead of guessing.

MCP stands for Model Context Protocol, and Claude, Codex, Cursor and many other AI apps speak it.

Every server I've made is on my MCP servers page.

The Bannerbear CLI is the same program as the Bannerbear MCP server, run as commands.

AI agents like Claude Code, Codex and OpenCode run them for you, and you can type them in a terminal or a script.

One npm package installs both.

Use the Bannerbear MCP server in an AI app with no terminal, like Claude Desktop's chat, and the CLI in a terminal, a script or a cron job.

In an AI app that can run commands, like Claude Code, Codex or Cursor, the CLI is the lighter choice, because it costs nothing until it runs.

Yes, the Bannerbear MCP server is free and open source under the AGPL-3.0-or-later license.

Renders, media tools and AI generation spend Bannerbear credits from your own plan.

No, the server uses Bannerbear's V5 API, and V2 keys don't work with it.

Make a V5 key on the V5 API Keys page.

Yes, a V5 key can be limited to read and write scopes for each part of your workspace, like images or templates.

A key with no scopes has full access.

Every render comes back as a job right away. poll_job checks that same job until it's done, or Bannerbear can call a webhook when it finishes.

Yes, the Bannerbear MCP server connects as many workspaces as you set up in BANNERBEAR_ACCOUNTS, each with its own key.

Every tool takes an optional account, and a workspace never borrows another one's key.

To disconnect the Bannerbear MCP server, delete or roll its key on the V5 API Keys page, which cuts access right away.

Then remove the server from your AI app's config.

The Bannerbear MCP server works with any app that speaks MCP.

That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code, Windsurf, Zed, Cline, GitHub Copilot CLI, Gemini CLI, OpenCode, OpenClaw, Antigravity and Hermes.

I did.

I'm Navid Moazzez, and I made the Bannerbear MCP server & CLI as one of my free tools on navid.me.

You can read more about me.

The code is on GitHub under the AGPL-3.0-or-later license, and the package is on npm.

More MCP servers & CLIs

Related free tools

Navid Moazzez

AI business strategist

Navid Moazzez helps creators and founders master AI and build their own AI Operating System (AI OS) to automate their business and life.

Navid.me is reader-supported. When you buy through links on this site, I may earn an affiliate commission. Read the affiliate disclaimer.

Free AI newsletter

The most actionable AI newsletter for founders

Every week, get proven AI strategies, curated tools, and step-by-step systems to grow your audience, create better content, and build a profitable creator business.

No fluff, no filler, no BS. Just five minutes each week that might level up your online business and life.

P.S. Sign up now to get free access to my ultimate AI tools guide for creators.

Loved by 10,000+ readers
Loved by 10,000+ readers