Viral Carousels with Gemini CLI
Generate Instagram carousel slides with Gemini CLI and Paper Design via MCP.
Introduction
30 Second Summary
Creating Instagram carousels by hand is slow. You design one slide, duplicate it, tweak the text, adjust the colors, and repeat until you have five slides that look consistent.
In this project, you will connect Google's Gemini CLI to a design tool called Paper Design using the Model Context Protocol (MCP). You'll type a topic and have Gemini generate a complete 5-slide Instagram carousel directly on your design canvas.
What You'll Build
An AI-powered Instagram carousel generator that turns a single text prompt into export-ready carousel slides using Gemini CLI and Paper Design.
By the end of this project, you'll have:
- A working Gemini CLI + Paper Design MCP connection that creates carousel slides directly on your design canvas.
- A set of 5 exported 1080x1350px carousel images at 2x resolution, ready to upload to Instagram.
- A reusable project context file that enables single-command carousel generation in the future.
- Secret Mission: Connect Firecrawl as a second MCP server to scrape real company logos and brand colors from the web, then inject them into a carousel slide.
Are there any prerequisites?
You need a Mac (Paper Design Desktop is macOS only) and a personal Google account for Gemini CLI authentication. Both tools are free to use.
Install Gemini CLI
Gemini CLI is Google's free AI agent for the terminal. It lets you type prompts and have an AI model execute tasks on your behalf. In this project, you will connect it to a design tool so it can create carousel slides for you automatically.
Before you can do anything with Gemini CLI, you need to install it and log in with your Google account. That is what this step covers.
In this step, get ready to:
- Install Gemini CLI on your Mac.
- Authenticate with your personal Google account.
Install Gemini CLI on your Mac
Gemini CLI is a command-line tool you run inside Terminal. Let's check if it is already on your machine, and install it if not.
- Press Cmd+Space to open Spotlight.
- Type Terminal and press Enter to open it.
- Check if Gemini CLI is already installed by running this command:
gemini --version
✔️ I see a version number
Gemini CLI is already installed. You can skip ahead to the authentication substep below.
ⓧ Command not found
Gemini CLI is not installed yet. Pick one of the install methods below.
Homebrew
Homebrew is a package manager for macOS that makes installing tools easy. If you already have it, this is the fastest path.
- Install Gemini CLI by running this command:
brew install gemini-cli
Seeing brew: command not found?
This means Homebrew itself is not installed. Install it first by running this command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Follow the prompts in your terminal. Once Homebrew is installed, run brew install gemini-cli again.
npm
If you already have Node.js 20+ installed, you can use npm instead.
- Install Gemini CLI globally by running this command:
npm install -g @google/gemini-cli
Why does this need Node.js 20+?
Gemini CLI is built in TypeScript and requires the Node.js runtime version 20.0.0 or higher to execute. If you do not have Node.js or your version is too old, use the Homebrew method instead.
- Verify the installation by opening a new terminal window and running:
gemini --version
You should see a version number printed in your terminal.
Still seeing command not found?
Close your current terminal window completely and open a fresh one. Your shell needs to reload its PATH to find the newly installed binary.
If it still does not work after reopening, the Homebrew post-install instructions may not have been applied. Run eval "$(brew shellenv)" and try gemini --version again.
Help me troubleshoot why gemini --version is not found after installing Gemini CLI via Homebrew on macOS.
Authenticate Gemini CLI
Now that Gemini CLI is installed, you need to sign in with your Google account. This connects the CLI to Google's free Gemini API tier.
- Start Gemini CLI by running:
gemini
- Gemini CLI will ask you how you want to authenticate. Select Sign in with Google.
- A browser window opens automatically. Sign in with your personal Google account and click Sign in.
- Return to your terminal after completing the sign-in flow in the browser.
You should see the Gemini CLI interactive prompt ready for input. This means authentication succeeded.
What does signing in give you?
Your personal Google account grants you 1,000 requests per day on the free tier. No credit card, no API key, and no Google Cloud project required.
Your credentials are cached locally so you will not need to sign in again on future sessions.
Browser did not open or authentication is stuck?
Make sure you are using a personal Google account, not a work or school account. Organization accounts may require additional Google Cloud configuration.
If the browser did not open automatically, look for a URL printed in the terminal. Copy and paste it into your browser manually.
Help me fix Gemini CLI authentication issues on macOS.
Your AI agent is ready. Next up, you will install Paper Design and connect it to Gemini CLI so your agent can create designs directly on a canvas.
Install Paper Design and Connect MCP
With Gemini CLI ready, you need a design tool it can actually control. That tool is Paper Design, a design canvas built on HTML and CSS that AI agents can read and write to directly.
The connection between Gemini CLI and Paper Design happens through the Model Context Protocol (MCP). MCP lets AI agents use external tools the same way you'd use a plugin. In this step, you will install Paper Design, wire it up to Gemini CLI via MCP, and confirm the two can talk to each other.
In this step, get ready to:
- Install Paper Design Desktop on your Mac.
- Connect Paper Design to Gemini CLI via MCP.
- Test the connection by creating a shape on your canvas.
Download and install Paper Design Desktop
Paper Design Desktop is a macOS app that runs a local MCP server in the background. When the app is open with a file loaded, Gemini CLI can connect to it and create, edit, or export designs on your canvas.
- Open paper.design/downloads in your browser.
- Download the macOS installer for Paper Desktop (latest version is v0.2.0).
- Open the downloaded file and drag Paper Design into your Applications folder.
- Press Cmd+Space to open Spotlight Search.
- Type Paper and press Enter to open Paper Design.
- Sign in with your email or Google account, or create a new account if you do not have one.
- Once signed in, click New File to create a blank canvas.
- Keep Paper Design open for the rest of the project. The MCP server only runs while the app is open with a file loaded.
What is Paper Design?
Paper Design is a design tool built on web standards (HTML and CSS). Its canvas speaks the same language as code, which means AI agents can create and manipulate designs without needing image-based workarounds.
The free tier gives you 100 MCP tool calls per week. No credit card required.
Paper Design not opening?
If macOS blocks the app with a security warning, go to System Settings then Privacy & Security and click Open Anyway next to the Paper Design entry.
Help me open Paper Design on my Mac
Add the Paper MCP server to Gemini CLI
Paper Design runs an MCP server on your machine at http://127.0.0.1:29979/mcp. You need to tell Gemini CLI where to find it so the two can communicate.
- Switch back to your Terminal.
- If you still have a Gemini session running from the previous step, exit it by typing /quit or pressing Ctrl+C.
- Add the Paper Design MCP server by running this command:
gemini mcp add --transport http paper http://127.0.0.1:29979/mcp
What does this command do?
- gemini mcp add registers a new MCP server with Gemini CLI.
- --transport http tells Gemini to use the HTTP transport protocol (Paper Design uses Streamable HTTP).
- paper is the name you are giving this server. You will see it listed under this name.
- http://127.0.0.1:29979/mcp is the local address where Paper Design's MCP server listens.
- Verify the server was added by running:
gemini mcp list
- You should see paper listed as a configured MCP server.
Don't see paper in the list?
Make sure Paper Design Desktop is open with a file loaded before running the add command. The MCP server only starts when a file is open.
Double-check that you typed the URL exactly as shown, including the /mcp path at the end.
Help me fix my MCP server configuration
Test the MCP connection
The configuration is saved, but you need to confirm Gemini can actually reach Paper Design and create something on the canvas.
- Start a new Gemini session by running:
gemini
- Type /mcp to see active MCP servers. Paper should appear as connected.
- Type the following prompt into Gemini:
Create a red rectangle in Paper.
- Gemini will ask you to approve an MCP tool call. Type y and press Enter to confirm.
- Switch to Paper Design. You should see a red rectangle on your canvas.
- Select the red rectangle in Paper Design and delete it so your canvas is clean for the next step.
Why approve tool calls?
MCP tool calls give Gemini permission to make changes in external apps. The approval prompt is a safety measure so you stay in control of what the AI agent does on your machine.
No rectangle appearing in Paper?
Confirm Paper Design is open with a file loaded. The MCP server only operates on the currently open file.
If /mcp shows Paper as disconnected, quit your Gemini session, restart Paper Design, then start a new session with gemini.
Help me troubleshoot my MCP connection
Your AI agent now has hands. It can reach into Paper Design and create whatever you describe. Next up, you will use this connection to generate a full Instagram carousel from a single prompt.
Generate Your First Carousel
Your MCP connection is live and Gemini can talk directly to Paper Design. Now it is time to put that connection to work.
In this step, you will type a single prompt and watch Gemini generate a complete 5-slide Instagram carousel on your Paper Design canvas. Then you will export the slides as high-resolution images ready for posting.
In this step, get ready to:
- Generate a 5-slide Instagram carousel in Paper Design using a text prompt.
- Export each slide as a 2x resolution PNG file.
Confirm your project folder and Gemini session
You should already have a Gemini session running from your instagram-carousels project folder on your Desktop.
- Switch back to your terminal. You should see the Gemini CLI interactive prompt waiting for input.
- Confirm Paper Design Desktop is still open with your blank canvas visible.
Don't see the Gemini prompt?
If you accidentally closed the session, return to your project folder and restart it by running:
cd ~/Desktop/instagram-carousels
gemini
Type /mcp to confirm the Paper server is still connected before continuing.
Help me reconnect Gemini CLI to Paper Design.
Prompt Gemini to generate your carousel
Gemini will use the Paper MCP tools to create artboards, write styled HTML content to each slide, and arrange them on your canvas. All you need to provide is a detailed prompt describing the carousel you want.
- Start your carousel generation by pasting this prompt into your Gemini session:
Create an Instagram carousel in Paper about "5 morning habits that changed my life". Each slide should be a 1080x1350 artboard. I want a handwritten style on a notebook that looks like I've written with a pen.
- Slide 1: Bold hook title
- Middle slides: One point per slide with a number and short description (create one slide for every point in the topic)
- Final slide: Call to action (Follow for more)
Add subtle styling like a thin border or accent color to tie the slides together.
Ask me some questions to better understand what I want to include in each slide.
What does this prompt do?
This prompt gives Gemini four pieces of information it needs to generate your carousel:
- The topic and number of slides (5 morning habits).
- The exact dimensions (1080x1350px, which is Instagram's 4:5 portrait ratio).
- The visual style (handwritten notebook aesthetic).
- The structure (hook, content slides, call to action).
The last line asks Gemini to clarify your preferences before building. This gives you control over the final result.
- Answer any questions Gemini asks about your slide content. These might include questions about colors, specific habits to feature, or font preferences.
- When you are happy with the plan, type "go" to tell Gemini to start building.
What happens when Gemini starts building?
Gemini will begin making MCP tool calls to Paper Design. Each tool call requires your approval before it runs. You will see a confirmation showing the server name, tool name, and arguments.
You can approve each call one at a time, or select the option to always allow tools from the Paper server for this session. This speeds things up since Gemini typically makes many calls to build a full carousel.
- Approve the MCP tool calls when prompted. You can select the "always allow this server" option to avoid repeated confirmations.
- Watch your Paper Design canvas as slides appear. You should see 5 artboards populate with styled content.
Switch to Paper Design to review your carousel. You should see 5 separate 1080x1350 artboards with a handwritten notebook aesthetic, thin border, and warm accent color tying the slides together.
Slides not appearing in Paper Design?
Make sure Paper Design Desktop is open with a file loaded. The MCP server only runs while the app is open.
If you see an error about the MCP connection failing, quit Paper Design and reopen it. Then type /mcp in your Gemini session to check the connection status.
Help me troubleshoot my Gemini CLI to Paper Design connection.
Export your slides as PNGs
Your carousel is built, but you need image files to upload to Instagram. Paper Design can export each artboard as a high-resolution PNG through the same MCP connection.
- Export your slides by typing this prompt in your Gemini session:
Export each slide as a 2x PNG into my project folder.
Why 2x resolution?
Exporting at 2x means each 1080x1350 artboard produces a 2160x2700 pixel image. Instagram compresses uploads, so starting with a higher resolution ensures your carousel stays crisp on retina displays.
- Approve the MCP tool calls when prompted.
- Confirm the PNGs appeared in your project folder by running this command in a separate terminal window:
ls ~/Desktop/instagram-carousels
You should see one PNG file per slide (5 files total) listed in the output.
Don't see any PNG files?
Check that your Gemini session is running from the ~/Desktop/instagram-carousels folder. Gemini exports relative to its working directory.
If the export failed, try the prompt again. Make sure Paper Design is still open and the canvas contains your artboards.
Help me find or re-export my carousel PNG files.
Your first AI-generated carousel is complete. Next up, you will recreate a carousel from a reference screenshot, proving Gemini can match an existing design style.
Recreate a Carousel from a Reference Image
Your first carousel proved that Gemini can generate slides from scratch. Now you will push it further by giving Gemini a visual reference to work from.
In this step, you will screenshot a carousel you like on Instagram and feed it to Gemini as a style reference. Gemini's multimodal capabilities let it read images and extract layout, color, and typography details to recreate in Paper Design.
In this step, get ready to:
- Screenshot a reference carousel from Instagram.
- Feed the screenshot to Gemini and generate a matching carousel.
- Export the recreated slides as 2x PNGs.
Screenshot a carousel you like
Instead of starting from a blank slate, you can give Gemini a visual target. Taking a screenshot of a real carousel gives Gemini concrete details about layout, spacing, and color to replicate.
- Open a carousel post you like on Instagram in your browser. For example: instagram.com/p/DX8dDCDja-3.
- Take a screenshot of one or more slides by pressing Cmd+Shift+4, then drag to select the slide area.
- Save or move the screenshot into your instagram-carousels folder on your Desktop.
- Rename the file to screenshot.png so you can easily reference it in the next substep.
Pick a carousel with a clear style
Choose a carousel that has distinct visual elements like bold colors, a specific font style, or a recognizable layout pattern. The more distinctive the style, the easier it is for Gemini to replicate it.
- Confirm the screenshot is saved by running:
ls ~/Desktop/instagram-carousels/screenshot.png
You should see the file path printed in your terminal output.
Feed the screenshot to Gemini and generate a matching carousel
Gemini CLI uses the @ symbol to reference local files. When you point it at an image, Gemini analyzes the visual content and uses it as context for its response.
- Return to your Gemini session in the terminal.
- Paste the following prompt to reference your screenshot and describe the new carousel:
@./screenshot.png Recreate this carousel in Paper. Match the layout, colors, and typography as closely as possible. Each slide should be a 1080x1350 artboard. Use my screenshot as the style reference but change the content to be about "3 Tools Every Designer Needs".
Ask me some questions to better understand what I want to include in each slide.
What does this prompt do?
The @./screenshot.png at the start tells Gemini to read the image file from your project folder. Gemini analyzes the layout, colors, and typography in the screenshot.
The rest of the prompt instructs Gemini to replicate that style while changing the content to a new topic. The final line asks Gemini to clarify details before generating, giving you control over what goes on each slide.
- Answer any questions Gemini asks about what you want on each slide.
- When you are happy with the plan, type go to start generation.
- Approve each MCP tool call when prompted (type y to confirm).
Switch to Paper Design. You should see new artboards appearing on your canvas that match the style of your screenshot but contain the new content about designer tools.
Request tweaks in real time
If the output does not quite match your reference, tell Gemini what to fix. For example: "Make the title text larger" or "Use a darker background color on slide 2". Gemini will update the existing artboards through MCP.
Slides don't match the reference style?
Make sure your screenshot file is named exactly screenshot.png and sits inside ~/Desktop/instagram-carousels. If the file is elsewhere, Gemini cannot find it.
Try being more specific in a follow-up prompt. Mention exact colors ("use #1a1a2e as the background") or layout details ("put the title centered at the top third of the slide").
Help me get Gemini to match my reference screenshot more closely in Paper Design.
Export the recreated slides
- In your Gemini session, type the following to export your new carousel:
Export each slide as a 2x PNG into my project folder.
Why 2x resolution?
Instagram displays images on high-density (Retina) screens. Exporting at 2x means your 1080x1350 artboard renders as a 2160x2700 pixel image. This keeps text and graphics crisp when viewed on phones and tablets.
- Approve the MCP tool calls when prompted.
- Confirm the new PNGs appear in your folder by running:
ls ~/Desktop/instagram-carousels
You should see both your original carousel PNGs from the previous step and the new set of PNGs for the recreated carousel.
Don't see the new PNG files?
Make sure you approved all MCP tool calls during the export. If you accidentally declined one, type the export prompt again and approve each call.
Check that Paper Design Desktop is still open. The MCP server only runs while the app is active with a file loaded.
Help me troubleshoot my PNG export from Paper Design via Gemini CLI.
You now have two complete carousels in your project folder. One generated purely from text, and one guided by a visual reference. Next up, you will save your preferences into a reusable project context file so future carousels take just one sentence to create.
Save a Reusable Project Context File
In the last step, you proved that Gemini CLI can recreate a carousel by reading a reference screenshot. But every time you start a new session, you have to re-explain your preferred slide size, style, and structure from scratch.
In this step, you will create a GEMINI.md project context file that Gemini CLI loads automatically from your working directory. It sends the file contents to the model with every prompt, so you never have to repeat your carousel preferences again.
In this step, get ready to:
- Create a GEMINI.md file with your carousel preferences (slide size, style, structure, workflow).
- Test the context file by generating a brand new carousel with a single sentence.
Create the GEMINI.md project context file
A GEMINI.md file is a context file that Gemini CLI discovers automatically in your working directory. The CLI concatenates its contents and sends them to the model with every prompt you type.
- Create the GEMINI.md file in your project folder by running this command:
touch ~/Desktop/instagram-carousels/GEMINI.md
- Confirm the file exists by running:
ls ~/Desktop/instagram-carousels/GEMINI.md
You should see GEMINI.md listed in the output.
- Open GEMINI.md in a text editor. You can open it from Terminal by running:
open ~/Desktop/instagram-carousels/GEMINI.md
- Paste the following content into GEMINI.md:
# Instagram Carousel Agent
## Task
When asked to create a carousel, generate Instagram carousel slides in Paper Design using the Paper MCP server.
## Defaults
- Artboard size: 1080x1350px (4:5 portrait ratio)
- Export: 2x PNG resolution
## Slide Structure
- Slide 1: Bold hook title
- Middle slides: One point per slide with a number and short description
- Final slide: Call to action (Follow for more)
## Style
- Handwritten notebook aesthetic
- Thin border on each slide
- Warm accent color to tie slides together
- Clean, readable typography
## Workflow
1. Use create_artboard to make each slide
2. Use write_html to add styled HTML content
3. Use export to save as 2x PNG
What does this file do?
Each section gives Gemini a specific piece of context it applies to every carousel request:
- Task tells Gemini its role and which MCP server to use.
- Defaults locks in the artboard dimensions and export resolution so you never have to specify them.
- Slide Structure defines the hook-points-CTA pattern for every carousel.
- Style sets the visual direction (handwritten notebook, warm accent color).
- Workflow tells Gemini exactly which Paper Design MCP tools to call and in what order.
- Save GEMINI.md in your text editor (Cmd+S).
File not saving correctly?
If open launched TextEdit and it is showing the file in Rich Text mode, click Format in the menu bar and select Make Plain Text before saving. GEMINI.md must be plain text, not formatted rich text.
Help me save GEMINI.md as plain text
✔️ Awesome, I've got everything!
Great. Double check you have saved GEMINI.md and it is in your instagram-carousels folder.
ⓧ I'd like to double check the full code
Here is the complete GEMINI.md file for comparison:
# Instagram Carousel Agent
## Task
When asked to create a carousel, generate Instagram carousel slides in Paper Design using the Paper MCP server.
## Defaults
- Artboard size: 1080x1350px (4:5 portrait ratio)
- Export: 2x PNG resolution
## Slide Structure
- Slide 1: Bold hook title
- Middle slides: One point per slide with a number and short description
- Final slide: Call to action (Follow for more)
## Style
- Handwritten notebook aesthetic
- Thin border on each slide
- Warm accent color to tie slides together
- Clean, readable typography
## Workflow
1. Use create_artboard to make each slide
2. Use write_html to add styled HTML content
3. Use export to save as 2x PNG
Test your project context with a one-sentence prompt
Now for the payoff. When you start a Gemini session from your instagram-carousels folder, the CLI automatically discovers your GEMINI.md and sends its contents with every prompt.
- Switch back to Paper Design and confirm it is still open with your canvas visible.
- Return to your terminal and make sure you are in the project folder by running:
cd ~/Desktop/instagram-carousels
- Start a new Gemini session by running:
gemini
You should see the Gemini interactive prompt appear. The CLI footer shows the number of context files loaded.
- Confirm your context is loaded by typing:
/memory show
You should see the contents of your GEMINI.md displayed in the output. This confirms Gemini has loaded your carousel preferences.
- Type this one-sentence prompt and press Enter:
Create a carousel about 3 tips for better sleep
- Approve the MCP tool calls when prompted.
Switch to Paper Design. You should see new 1080x1350 artboards appearing on your canvas using the handwritten notebook style and warm accent color you specified in GEMINI.md.
Why does a one-sentence prompt work now?
Gemini already knows the artboard size, slide structure, visual style, and which MCP tools to call because it read your GEMINI.md at session start. You no longer need to spell out dimensions, export settings, or slide layout in every prompt.
Not seeing new artboards in Paper?
- Make sure Paper Design Desktop is open with your canvas file visible. The MCP server only runs while the app is open with a file loaded.
- Run /memory show inside your Gemini session. If your GEMINI.md content does not appear, confirm you are running gemini from the ~/Desktop/instagram-carousels folder.
- Run /mcp to check that the Paper server shows as CONNECTED.
Help me troubleshoot my GEMINI.md context and MCP connection
You now have a reusable carousel generation system. Any time you want a new carousel, just open Paper Design, start a Gemini session from this folder, and type a single sentence describing your topic.
Secret mission
Connect Firecrawl for Live Brand Data
What if your carousel slides could pull real brand assets directly from any company's website? Connect a second MCP server to Gemini CLI and scrape live logos, colors, and fonts from the web, then inject them into a carousel slide.
Clean Up Your Resources
Clean Up Your Resources
This project runs entirely on free tools with no ongoing costs. Decide whether to keep your resources for future carousel generation, pause them to free up system resources, or delete everything.
Resources you used:
- Gemini CLI (installed on your Mac via Homebrew or npm, free tier).
- Paper Design Desktop app (v0.2.0, free tier).
- Paper Design canvas file containing your carousel artboards.
- MCP server configurations (paper and firecrawl).
- Project folder at ~/Desktop/instagram-carousels (GEMINI.md, exported PNGs, screenshot).
Keep everything running
No action needed. No costs are accumulating. Keep Paper Design installed and your GEMINI.md file in your project folder for future carousel generation.
Your Gemini CLI free tier refreshes daily (1,000 requests/day). Paper Design gives you 100 MCP tool calls per week. You can generate new carousels anytime by opening Paper Design and running gemini in your project folder.
Pause - I'll come back to this later
Shut down running processes to free up memory. Your project files and configuration stay on disk for when you return.
- Quit Paper Design Desktop (the MCP server stops when the app closes).
- Your project folder, GEMINI.md, and exported images remain at ~/Desktop/instagram-carousels.
- Your MCP server configurations remain saved in your Gemini CLI settings.
To resume later, reopen Paper Design Desktop with your canvas file, then start a new Gemini session in your project folder.
Delete - I don't want to use this again
Remove all project resources and installed tools. Follow each step below.
- Delete your project folder by running this command in Terminal:
rm -rf ~/Desktop/instagram-carousels
- Remove your MCP server configurations by running:
gemini mcp remove paper
gemini mcp remove firecrawl
- In Paper Design, delete the canvas file containing your carousel artboards (right-click the file in your files list and select delete).
- To uninstall Paper Design Desktop, drag it from your Applications folder to Trash.
- To remove Gemini CLI, run one of the following depending on how you installed it:
Homebrew
brew uninstall gemini-cli
npm
npm uninstall -g @google/gemini-cli
Nice Work!
Nice Work!
You just built an AI-powered Instagram carousel system using Gemini CLI and Paper Design, turning a single text prompt into polished, export-ready slides. And it cost you $0.
You've learned how to:
- Connected Paper Design to Gemini CLI via MCP, giving a free AI agent direct access to a design canvas.
- Generated complete Instagram carousels from text prompts and reference screenshots, with professional typography and styling across multiple slides.
- Created a reusable GEMINI.md project context file that lets you generate new carousels with a single command in the future.
- Connected Firecrawl as a second MCP server to scrape live brand assets from the web and inject real logos and colors into carousel slides.
Ready to quiz yourself?