carousels-mcp

MCP server that turns articles, transcripts, and markdown into LinkedIn carousel PDFs, Instagram PNGs, and Threads PNGs. Content in, slides out. No web UI, no cloud service.

Where this came from

I'd been building LinkedIn carousels manually -- Gemini for the content distillation, SVG generation for the slides, Puppeteer for the PDF conversion, then merging everything together. The whole process is documented in this article. It worked well but it was a lot of steps. So I packaged the pipeline into an MCP server. Now Claude handles the orchestration and I just tell it what I want.

What it does

You've got an article or a YouTube transcript or some markdown notes and you want a carousel. This server handles everything: content extraction, slide planning, SVG generation, PDF/PNG output. Give it a URL and it scrapes the content. Give it just a topic and it tells Claude how to research first using other MCP tools, then call back with the results.

The content extractor is actually quite good at picking the right slide type automatically. Numbers and percentages become stat slides. Ordered lists become step-by-step slides. Strong emphasis becomes takeaway callouts. "Before/after" language triggers comparison slides. The usual content, list, and quote types are there obviously, plus code slides for technical content and a CTA slide at the end.

The five tools

Eleven slide types

cover · content · code · quote · list · cta · stat · comparison · steps · takeaway · dataviz

Multi-platform output

Each platform gets the right dimensions and format. No fiddling with resize tools.

• LinkedIn -- 1080x1350, merged into a single PDF carousel
• Instagram -- 1080x1080, individual PNG slides at 2x resolution
• Threads -- 1080x1350, individual PNGs

Getting started

Claude Desktop config

{
  "mcpServers": {
    "carousels": {
      "command": "npx",
      "args": ["-y", "@houtini/carousels-mcp"],
      "env": {
        "CAROUSEL_TEMPLATES_DIR": "/path/to/your/brand-kits"
      }
    }
  }
}

CAROUSEL_TEMPLATES_DIR is optional. Skip it if you're fine with the built-in templates.

Or install globally:

npm install -g @houtini/carousels-mcp

PDF and PNG output

SVG generation works out of the box. For the actual PDF and PNG files you need Puppeteer:

npm install -g puppeteer

Without it everything still works -- you just get SVG files. The server tells you this in its response, so you'll know. For most workflows you want Puppeteer installed. The SVG-only path is there as a fallback.

Gemini MCP integration

This is where it gets interesting. If you've got Gemini MCP installed alongside carousels-mcp, the two servers work together through Claude's orchestration. The carousel server can't see Gemini's tools directly -- MCP servers are isolated from each other -- but the tool descriptions teach Claude how to compose them.

What that means in practice:

• Research-first carousels. Give create_carousel just a topic and it returns orchestration instructions. Claude picks up the workflow, calls gemini_deep_research for the content, then calls back with the results. You get a carousel about a topic you haven't written about yet.
• Custom charts. Use preview_slides to get a slide plan, then ask Gemini's generate_svg to create charts or diagrams for specific slides. Inject the SVGs into the plan's customSvg fields and call render_slides. The chart ends up embedded directly in the slide.
• Quality review. After rendering, Gemini's analyze_image can review the output PNGs and suggest improvements. Useful for catching text overflow or layout issues before you upload.

You don't need Gemini MCP for the core pipeline to work. Content in, carousel out -- that works standalone. But the research and visual enhancement workflows are quite good when both servers are available.

Workflow examples

URL to carousel -- the most common one. Give it an article URL, get a carousel back.

"Turn this into a LinkedIn carousel: https://example.com/my-post"

Topic to carousel -- when you haven't written the content yet. Claude researches via Gemini, then builds the slides.

"Make me a carousel about breeding pigs for LinkedIn"

YouTube to carousel -- works with Supadata MCP for transcript extraction.

"Turn this YouTube video into a carousel: https://youtube.com/watch?v=..."

Data-driven with charts -- research, analyse, then generate chart SVGs to embed in the slides.

"Research renewable energy trends, analyse the data, and make a carousel with charts"

Preview, tweak, render -- when you want to review the slide plan before committing.

"I want to review the slides before generating"
→ preview_slides returns editable JSON
→ You adjust slides, swap types, reorder
→ render_slides produces the final output

Templates

Six built-in templates. I spent a fair amount of time on these -- proper font pairings, warm backgrounds, committed colour palettes. No cold whites, no Inter, no generic SaaS aesthetic.

Custom brand kits

Use create_template to build your own. Pick a base template, override the colours and fonts you care about, and it saves a JSON file to your templates directory. Next time you run list_templates, your brand kit shows up alongside the built-ins.

The server is fairly smart about brand detection. If you have custom templates but you're using the default professional, it mentions your brand kits in the response. Gentle nudge, not a nag.

Engagement patterns

There's some deliberate design baked into the SVG generation. Not decorative stuff -- actual patterns from LinkedIn carousel performance research.

Progress bar. Every slide gets a gradient bar at the bottom showing position in the deck. The Zeigarnik effect means people who see "3 of 8" feel compelled to keep swiping. It's thin and unobtrusive, but it works.

50 words per slide maximum. The content extractor enforces this. More than about three seconds of reading time per slide and people scroll past. If your content runs long, it gets split across more slides rather than cramming text in.

Slide 5 anchor. The extractor deliberately places a stat or quote slide at position 5. Mid-carousel drop-off is a real thing and an attention-grabbing slide at that position helps retention.

Output structure

Carousels save to ~/Documents/carousels/ in date-stamped folders:

~/Documents/carousels/2026-03-14-my-article-title/
  slide-01.svg
  slide-02.svg
  ...
  slide-01.pdf       (LinkedIn)
  carousel.pdf       (merged, ready to upload)
  slide-01.png       (Instagram/Threads)
  slide-02.png

Override with outputDir parameter or the CAROUSEL_OUTPUT_DIR environment variable.

Tool reference

create_carousel

The full pipeline. Three input modes:

• Content mode: Pass content directly -- runs the pipeline immediately.
• URL mode: Pass sourceUrl -- the server fetches the page, extracts article content, runs the pipeline. If the page is JS-rendered and extraction fails, it returns fallback instructions to use firecrawl_scrape or web_fetch instead.
• Topic mode: Pass topic without content or URL -- returns orchestration workflows telling Claude how to research first, then call back with content.

preview_slides

Returns a JSON slide plan you can review and edit before rendering.

render_slides

Renders a slide plan (from preview_slides or hand-crafted) to SVG + PDF/PNG.

list_templates

Lists built-in and custom templates. No parameters.

create_template

Creates a custom brand kit from a base template.

Environment variables

Requirements

• Node.js 18+
• Puppeteer (optional, for PDF/PNG output)
• Gemini MCP (optional, for research workflows and custom chart generation)

Licence

MIT