pinmuse

An open-source AI design agent that studies Pinterest and makes the post.

Posters, Instagram stories, carousels and pins with real typography, from one sentence. Agent Skill, CLI and MCP server for Claude Code, Codex, Gemini CLI and any MCP client.

Website · Gallery · Install · Usage · Image models · FAQ

You ask your agent for "a dark-academia story for my book club". pinmuse searches Pinterest, reads the palette, light and mood of the pins it finds, writes an image prompt that leaves room for type, generates the picture with whatever model you have, and sets the headline itself. You get a finished file, a caption with hashtags, and credits for the pins it learned from.

No screenshots, no copy-pasting pins, no design app.

Gallery

Each design is a single pinmuse create command. Images by gpt-image-2.5-flare; layout and type by pinmuse.

Carousels get a new photo on every slide: a cover, numbered slides and an end card. Give each slide a subject and pinmuse generates a picture for it.

The raw generations underneath each design are in outputs/photos. More on the website.

Related MCP server: pinterest-mcp

Install

curl -fsSL https://raw.githubusercontent.com/prantikmedhi/pinmuse/main/install.sh | bash

This installs the CLI and links the skill into every agent it finds (Claude Code, Codex, Gemini CLI, Antigravity, opencode, OpenClaw, Hermes, Cursor). Add --mcp to register the MCP server too.

CLI only: pip install "pinmuse[mcp] @ git+https://github.com/prantikmedhi/pinmuse"

Usage

Ask your agent:

Make an Instagram story for our Friday rooftop party. Get the vibe from Pinterest: vaporwave sunset.

Or run it yourself:

pinmuse create "rooftop party at sunset" --inspo "vaporwave sunset aesthetic" \
  -t story -f ig-story --title "Sunset Club" --subtitle "Friday • rooftop • 8pm" --cta "RSVP in bio"

pinmuse-out/20261103-201500-sunset-club/
├── story-ig-story.jpg   the post
├── base-1.png           the generated image
├── moodboard.jpg        the pins it learned from
├── caption.txt          caption and hashtags
└── manifest.json        prompt, palette, model, pin credits

Step by step, the way the skill teaches agents to work:

pinmuse suggest   "cozy reading"                 # Pinterest's own related searches
pinmuse moodboard "dark academia library"        # palette, mood, aesthetic, contact sheet
pinmuse generate  "<prompt>" -f ig-post --refs pin1.jpg,pin2.jpg
pinmuse compose   -t quote -f ig-post --image generated.png --title "Paradise is a kind of library."

Carousels take a slides file; each slide's subject becomes its own image:

pinmuse create "salt flat mirror at sunset" -t carousel --slides slides.json --title "Places that look unreal"
# slides.json: [{"title": "Zhangjiajie, China", "body": "Pillars in the fog.", "subject": "sandstone pillars in fog at dawn"}, …]

How it works

1. Explore Pinterest by phrase, pin URL or board URL, signed out and throttled. The official API covers your private boards.

2. Distill the palette, brightness, contrast, warmth and recurring motifs, and match them against 14 aesthetics. The agent also looks at a contact sheet.

3. Prompt for the subject and the learned direction, with empty space where the text will go. The model never draws text.

4. Generate with your model. OpenAI and Gemini can take 2–4 pins as style references.

5. Compose with real fonts, auto-fit, safe zones, grain and your brand kit.

6. Ship the post plus caption.txt and manifest.json with pin credits.

Image models

--provider auto uses the first one configured. pinmuse list providers shows what is set up.

If your agent already has an image tool, it can generate there and run pinmuse compose --image on the result.

Templates and formats

Templates poster magazine story quote polaroid minimal swiss collage palette carousel

Formats Instagram post, square, story and reel cover · Pinterest pin and long pin · X · LinkedIn · YouTube thumbnail · Facebook cover · A3 and 18×24 posters · wallpapers · any WIDTHxHEIGHT

Aesthetics minimal luxe, dark academia, clean girl, Y2K, cottagecore, cyberpunk neon, coastal summer, brutalist, old money, vaporwave, moody film, pastel dream, earthy boho, gothic romance (guide)

Brand kit --brand brand.json with your handle, palette, fonts and logo.

Every command prints JSON; errors are {"ok": false, "error": …}.

MCP tools pinterest_search pinterest_suggest pinterest_moodboard build_prompt generate_image compose_design create_design list_options

Settings can also live in ~/.config/pinmuse/config.json.

FAQ

Is reading Pinterest allowed? pinmuse reads public pages signed out, cached and throttled to human volume, and never asks for your password. Use the official API for private boards, and check Pinterest's terms for commercial use.

Will it copy someone's pin? No. Pins set the direction: palette, light, composition. The skill forbids reproducing pins, people, logos or watermarks, and every manifest.json credits the pins used.

Do I need an API key? No. Without one you get typographic designs on procedural backgrounds. A gpt-image, Gemini or Flux key gives photographic results like the gallery.

Which platforms? Instagram, Pinterest, TikTok covers, X, LinkedIn, YouTube, Facebook and print.

Contributing

git clone https://github.com/prantikmedhi/pinmuse && cd pinmuse
pip install -e ".[dev,mcp]" && pytest -q

New aesthetics, templates and providers are welcome. See CONTRIBUTING.md.

MIT © Prantik Medhi · Fonts under the SIL Open Font License · Not affiliated with Pinterest.