CarouselMCP

An MCP server that generates a ready-to-post Instagram carousel — a "notebook paper" style set of PNG slides — from nothing but a topic string. Deployed as a single AWS Lambda function behind a public Function URL, with generated images stored in S3.

What it does

One tool, generate_skill_carousel, takes a topic and returns a finished carousel:

{
  "name": "generate_skill_carousel",
  "arguments": { "topic": "python libraries every data engineer should know" }
}

A single AI call — Gemini or Claude, whichever key is available — does all the creative work at once:

• Picks the layout itself. Most topics get the default list layout: a hook slide, four grid pages of items, and a closing slide (6 slides, up to 32 items total). A genuine two-sided topic ("Claude pros and cons", "remote work advantages and disadvantages") is automatically routed to the pros_cons layout instead — hook, a green PROS slide, a red CONS slide, a verdict slide, a recap slide, and closing. This is a semantic decision by the model, not keyword matching on the topic string.

• Decides how many items the topic actually supports — it won't pad a thin topic out to a fixed count.

• Grounds the content in a real web search (Google Search via Gemini, or Claude's built-in web_search tool) instead of writing from the model's own unverified memory.

Every icon is a built-in flat vector glyph — there's no AI image generation anywhere in the pipeline, and none is needed. No background image, hero photo, reference image, or custom theme/colors are accepted as input; the paper-texture background, fonts, and doodle accents are all fixed. That's a deliberate trim, not a missing feature — topic (plus an optional API key override) is the entire input surface.

Related MCP server: mcp-media-toolkit

Requirements

• One of GEMINI_API_KEY or ANTHROPIC_API_KEY (env var, or pass geminiApiKey / claudeApiKey per call to override). Gemini is tried first if both are present. If neither is available or both fail, it falls back to placeholder text rather than failing the whole call.

  • Note: Claude has no image-generation API and isn't used for one here — it's only ever used for the text content, same as Gemini's role in this pipeline.

• OUTPUT_BUCKET — an S3 bucket the function can write PNGs to (defaults to my-custom-mcp in code; override for your own bucket).

• MCP_API_KEY — shared secret every caller must send. Fails closed: a missing or wrong key is rejected with 401 before any model call or S3 write happens, so a bad key never costs anything.

• Bundled fonts. Lambda has no system fonts, and image rendering needs real font files — fonts/NotoSans-Regular.ttf, fonts/NotoSans-Bold.ttf, and fonts/fonts.conf are committed in this repo and must ship inside the deployment package, with FONTCONFIG_PATH=/var/task/fonts set as an environment variable.

Deploying

Option A — one command, via AWS SAM

sam build --use-container
sam deploy --guided

--use-container matters here — sharp (the image library this uses) ships a native binary compiled for a specific OS/architecture. Building without a container compiles against whatever machine you're running sam build on; building in a container cross-compiles against Lambda's actual Linux runtime, avoiding a broken/mismatched native binary at runtime.

--guided prompts for the stack name, region, and the two parameters (GeminiApiKey / AnthropicApiKey — provide at least one; both are NoEcho) on first run, then remembers your answers in samconfig.toml.

Option B — manual, via the Lambda console

1. npm install.

2. Zip the folder's contents (not the folder itself) — index.mjs, node_modules, package.json, package-lock.json, and the fonts/ folder all need to sit at the zip's top level.

3. Create function → author from scratch → Node.js 22+ → upload the zip.

4. Configuration → General configuration: raise Timeout (this one's deployed at ~2 minutes) and Memory (deployed at 256 MB — image compositing needs more headroom than plain text generation).

5. Configuration → Environment variables: MCP_API_KEY, OUTPUT_BUCKET, FONTCONFIG_PATH (/var/task/fonts), and at least one of GEMINI_API_KEY / ANTHROPIC_API_KEY.

6. Permissions: attach s3:GetObject, s3:PutObject, s3:PutObjectAcl, and s3:DeleteObject on your output bucket — the function reads, writes, and can clean up its own generated objects.

7. Configuration → Function URL: create one with Auth type NONE. MCP_API_KEY, checked inside the handler, is the real gate — NONE here only means AWS isn't checking IAM signatures.

Testing it directly

curl -s https://<your-function-url> \
  -H "x-api-key: <MCP_API_KEY>" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://<your-function-url> \
  -H "x-api-key: <MCP_API_KEY>" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"generate_skill_carousel","arguments":{"topic":"python libraries every data engineer should know"}}}'

The response includes both a text summary and structuredContent with the topic, slide count, and the direct S3 URLs for each generated PNG.

Connecting an MCP client

claude mcp add --transport http carousel https://<your-function-url> \
  --header "x-api-key: <MCP_API_KEY>"

Project structure

index.mjs   — everything: carousel generation, image rendering, S3 I/O, JSON-RPC dispatch
fonts/      — fonts bundled into the deployment package (no system fonts on Lambda)
package.json

Security note

MCP_API_KEY, GEMINI_API_KEY, and ANTHROPIC_API_KEY are all plain environment variables — never hardcode them in index.mjs. Rotate all three if this function's configuration was ever shown on screen (a demo, a screen recording).