Storeshots MCP Server

storeshots-mcp

Generate App Store and Google Play screenshots from the command line, or let your AI coding agent do it.

storeshots turns raw app screenshots into finished store-listing visuals — device frames, benefit-driven headlines, brand backgrounds, and exact store dimensions for iOS and Android. Describe your whole listing in one storeshots.json, run storeshots build, and get every platform in every language. Your AI agent (or you) writes and translates the copy; storeshots renders the pixels. It's a CLI first, with an MCP server for agents that have no shell. No design tool, no subscription, no API keys.

---

The idea

Store screenshots are two jobs pretending to be one. There's a creative job (what to say, which screen sells which feature, how to phrase it in six languages) and a production job (frames, typography, exact pixel dimensions, no alpha channel). Design tools make you do both by hand; screenshot SaaS locks the production job behind a subscription.

storeshots-mcp splits them and gives each to whatever is best at it:

Because the render path is pure and local, the same inputs always produce the same pixels — no model in the loop, nothing uploaded anywhere.

Quick start

npx storeshots init --langs en,tr --bg "#E31837"   # finds ./screenshots, writes storeshots.json
# replace the TODO headlines in storeshots.json
npx storeshots build --watch                       # renders everything, re-renders on save

init lists your raw screenshots (from screenshots/, raw-shots/, raw/, shots/ or fastlane/screenshots/, or --screens <dir>) in a config like this:

{
  "background": "#E31837",
  "presets": ["ios-phone", "android-phone"],
  "languages": ["en", "tr"],
  "outputDir": "output",
  "screens": [
    { "screenshot": "screenshots/home.png",
      "copy": { "en": ["Track", "your daily mood"], "tr": ["İzle", "günlük ruh halini"] } },
    { "screenshot": "screenshots/stats.png", "variant": "tilted",
      "copy": { "en": ["Discover", "weekly insights"], "tr": ["Keşfet", "haftalık içgörüler"] } }
  ],
  "featureGraphic": { "screen": 1 },   // optional: Play Store 1024 × 500 header
  "showcase": true                     // optional: one preview strip per set
}

build renders every screen × preset × language:

output/
  en/ios-phone/en_01.png … en_06.png
  en/android-phone/en_01.png …
  en/play-feature-graphic/en_feature.png
  tr/ios-phone/tr_01.png …
  showcase/en_ios-phone.png …

Rendering is deterministic, so build only redraws what changed: edit one Turkish headline and only that file is rendered again. Delete a screen and its old files are removed. Every output is checked against its store's rules before it's written.

Install globally with npm i -g storeshots-mcp if you'd rather type storeshots than npx storeshots.

Commands

After a first successful build, storeshots asks once whether you'd like to star it on GitHub. It never asks in CI; set STORESHOTS_NO_STAR=1 to turn it off. Every command takes --json for machine-readable output and --help for details. Exit codes: 0 ok, 1 render or validation failure, 2 bad usage or config. Config errors list every problem at once, each with its path (screens[2].copy.tr: missing).

Config reference

With an AI agent

storeshots splits the creative work from the production work. Your agent reads your app, picks a benefit for each screen, writes and translates the headlines into storeshots.json, and runs storeshots build. That needs no setup in any agent that has a shell: Claude Code, Cursor, Codex, Windsurf and others. For the guided flow, install the Claude Code plugin.

"Take the screenshots in ./raw-shots and make a full App Store and Play Store set. Brand color #E31837, English and Turkish."

MCP server. For clients without a shell (Claude Desktop, for example), the same engine runs as a stdio MCP server:

claude mcp add storeshots -- npx -y storeshots-mcp

{ "mcpServers": { "storeshots": { "command": "npx", "args": ["-y", "storeshots-mcp"] } } }

Codex CLI uses ~/.codex/config.toml:

[mcp_servers.storeshots]
command = "npx"
args = ["-y", "storeshots-mcp"]

What it produces

5 presets, each at the exact size its store requires:

And the finishing touches that make a set look designed:

• Built-in device frames — iPhone (dynamic island), Pixel-style Android (punch hole), iPad, and tablet, drawn programmatically at exact scale. Bring your own with custom frames.
• Layout variants — text-top, text-bottom, and tilted; mix them across a set so it doesn't look like one template copied six times.
• Panoramic sets — one gradient flowing continuously across every panel, so the row reads as a single image in the store. See panoramas.
• Benefit-first headlines — a bold verb plus a short descriptor, auto-uppercased with locale-correct special characters and contrast-aware color.
• Showcase composer — one wide preview image of the whole set for your repo, launch post, or client deck.

Every output is flattened to remove the alpha channel that App Store Connect rejects, and validated against its preset before it's written.

MCP tools

Each tool returns file paths plus a structured summary, so the agent can review and iterate.

Multi-language sets

Translation happens in the agent, not in storeshots. Add a language key to each screen's copy and storeshots renders it with locale-correct casing: Turkish i → İ, German ß is kept. storeshots build --lang de rebuilds a single language.

Panoramic sets

Add "panorama": { "to": "#1E3A8A" } and each panel's solid background becomes one horizontal gradient sliced across the whole set. Placed side by side in the store, the screenshots then read as a single continuous image.

Custom frames

Prefer a specific device look? Supply your own frame PNG (transparent where the screen shows through) and the pixel rectangle the screenshot fills:

{
  "frame": {
    "image": "./frames/iphone-16-pro.png",
    "screenX": 40, "screenY": 40,
    "screenWidth": 1080, "screenHeight": 2280
  }
}

Use it as "frame" in storeshots.json, either one frame for every preset or { "ios-phone": {…}, "android-phone": {…} }. You can also pass it to storeshots compose --frame frame.png --frame-screen 40,40,1080,2280, or to the compose_screenshot and generate_set tools. Paths are relative to the config, and a changed frame image triggers a re-render. Leave it out to use the built-in frames.

Agent setup

Project instructions. storeshots init adds a short, marker-delimited storeshots section to your project's agent instruction file. Coding agents (Claude Code, Codex, Cursor and others) then know how this project's screenshots are made: edit storeshots.json, run storeshots build, and never hand-edit the PNGs.

• It uses AGENTS.md and/or CLAUDE.md, whichever already exist. When CLAUDE.md just imports @AGENTS.md, only AGENTS.md gets the section.
• If neither file exists, it creates AGENTS.md plus a CLAUDE.md that imports it.
• Rerunning updates the section in place. --no-agents skips it, and storeshots init --agents-only adds it to an existing project.

Claude Code plugin. The bundled skill adds a guided workflow. It discovers a benefit for each screen from your codebase and gets your approval on headlines before rendering. It then keeps storeshots.json up to date, adds languages, and walks you through the upload.

/plugin marketplace add mtbun/storeshots-mcp
/plugin install storeshots@storeshots

Then ask Claude Code for "store screenshots for this app".

llms.txt summarizes the commands and config format in one file for agents.

Design principles

1. Deterministic — no AI image generation in the render path; same input, same pixels.
2. Zero config — no API keys, no accounts, fully offline.
3. Store-correct by construction — dimensions are enforced and validated, not suggested.
4. Agent-native — tools expose structured data; the copywriting stays in the model where it belongs.

Roadmap

• Claude Code skill with a guided benefit-discovery workflow
• Play Store feature graphic preset (1024 × 500)
• Layout variants — text-top, text-bottom, tilted
• Custom device frames
• Panoramic sets
• Project config with incremental build and --watch
• Claude Code plugin and AGENTS.md / CLAUDE.md integration
• App preview video frames
• More stores (Mac App Store, Chrome Web Store)

Contributing

Issues and PRs welcome. AGENTS.md documents the architecture and conventions, for human contributors and coding agents alike.

License

MIT