Content
# storeshots-mcp
**Store-ready App Store and Google Play screenshots, generated by your AI agent.**
An MCP (Model Context Protocol) server that turns raw app screenshots into polished, pixel-perfect store listing visuals: device frames, bold benefit-driven headlines, brand colors, and exact store dimensions for iOS and Android. Your agent writes the copy, storeshots renders the pixels.
<!-- hero showcase image: assets/showcase.png -->
<p align="center">
<img src="assets/showcase.png" alt="Showcase of generated App Store and Google Play screenshots" width="100%" />
</p>
<p align="center">
<a href="https://www.npmjs.com/package/storeshots-mcp"><img src="https://img.shields.io/npm/v/storeshots-mcp?color=cb3837&label=npm" alt="npm version" /></a>
<a href="https://github.com/mtbun/storeshots-mcp/actions/workflows/ci.yml"><img src="https://github.com/mtbun/storeshots-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
<img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version" />
<img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" />
<img src="https://img.shields.io/badge/MCP-stdio-8A2BE2" alt="MCP stdio" />
</p>
## Why
Making store screenshots is the least fun part of shipping an app. Design tools are manual, screenshot SaaS products are paid and template-locked, and fastlane frameit only frames iOS devices without any marketing layer.
storeshots-mcp takes a different approach. It splits the job the way it should be split:
| The agent (Claude, Cursor, etc.) | The server (storeshots) |
|---|---|
| Reads your codebase, finds the benefits | Renders text with pixel-perfect typography |
| Writes punchy headlines | Composes device frames and backgrounds |
| Translates copy into any language | Enforces exact store dimensions |
| Picks which screen sells which feature | Outputs deterministic, reviewable PNGs |
No API keys. No accounts. No image-generation costs. Everything renders locally and deterministically, so the same input always produces the same output.
## Quickstart
### Claude Code
```bash
claude mcp add storeshots -- npx -y storeshots-mcp
```
### Claude Desktop / Cursor / Windsurf / Antigravity / VS Code
Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, or equivalent):
```json
{
"mcpServers": {
"storeshots": {
"command": "npx",
"args": ["-y", "storeshots-mcp"]
}
}
}
```
### Codex CLI
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.storeshots]
command = "npx"
args = ["-y", "storeshots-mcp"]
```
storeshots-mcp is a plain stdio MCP server with zero client-specific behavior, so it runs in any MCP-capable agent: Claude Code, Claude Desktop, Cursor, Windsurf, Antigravity, Codex, Gemini CLI, VS Code, Zed, and whatever ships next week.
Prefer no server at all? The same engine is available as a CLI:
```bash
npx storeshots compose --preset ios-phone --bg "#E31837" \
--verb "TRACK" --desc "YOUR DAILY MOOD" \
--screenshot ./raw/home.png --output ./out/en_01.png
```
Then just ask:
> "Take the screenshots in ./raw-shots and generate a full App Store and Play Store set. Brand color #E31837, 6 screenshots per platform, English and Turkish."
## What you get
- **5 presets** with exact store-required dimensions:
| Preset | Store | Dimensions |
|---|---|---|
| `ios-phone` | App Store, iPhone 6.9" | 1320 × 2868 |
| `android-phone` | Google Play, phone | 1080 × 1920 |
| `ipad-13` | App Store, iPad Pro 13" | 2064 × 2752 |
| `android-tablet` | Google Play, 10" tablet | 1600 × 2560 |
| `play-feature-graphic` | Google Play, feature graphic (landscape header) | 1024 × 500 |
- **Device frames** for iPhone (dynamic island), Pixel-style Android (punch hole), iPad, and Android tablet, drawn programmatically at exact scale
- **Benefit-first headline layout**: a bold action verb plus a short descriptor, sized and positioned for store shelf impact
- **Smart contrast**: text color flips between light and dark based on background luminance
- **Full Unicode typography**: bundled OFL-licensed font renders İ, Ğ, Ş, Ü, ß, and accented characters correctly in all caps
- **Showcase composer**: one wide preview image of the whole set, ready for your repo, tweet, or client deck
## Tools
| Tool | Description |
|---|---|
| `list_presets` | Returns all platform presets with dimensions and layout metrics |
| `compose_screenshot` | Renders one screenshot: background, device frame, headline, source image |
| `generate_set` | Batch-renders a full ordered set for one platform and language |
| `create_showcase` | Composes a preview strip from generated screenshots |
| `validate_screenshot` | Checks an image against store dimension and format requirements |
Every tool returns file paths plus a structured summary, so the agent can review output and iterate.
## Multi-language sets
Translation happens in the agent, not the server. Generate your English set, then ask for any locale:
> "Now generate the same set in Turkish and German."
The agent translates the headlines idiomatically, and storeshots renders them with correct locale-specific casing and special characters. Output follows a clean convention:
```
output/
en/ios-phone/en_01.png … en_06.png
tr/ios-phone/tr_01.png … tr_06.png
de/android-phone/de_01.png … de_06.png
```
## Claude Code skill (optional)
The MCP tools work on their own, but the bundled skill adds a guided workflow: benefit discovery from your codebase, headline approval before rendering, per-language sets, and upload guidance. Install it with:
```bash
mkdir -p ~/.claude/skills/storeshots
curl -o ~/.claude/skills/storeshots/SKILL.md \
https://raw.githubusercontent.com/mtbun/storeshots-mcp/main/skill/SKILL.md
```
Then ask Claude Code for "store screenshots for this app" and it walks the full flow.
## Design principles
1. **Deterministic**: no AI image generation in the render path. Same input, same pixels, every time.
2. **Zero config**: no API keys, no sign-ups, works fully offline.
3. **Store-correct by construction**: output dimensions are enforced, not suggested.
4. **Agent-native**: tools expose structured data, and the copywriting intelligence stays in the model where it belongs.
## Roadmap
- [x] Claude Code skill layer: guided benefit-discovery workflow on top of the MCP tools
- [x] Play Store feature graphic preset (1024 × 500)
- [ ] Layout variants: device-bottom, device-tilted, text-bottom
- [ ] Custom device frame support
- [ ] Panoramic sets (one background flowing across multiple screenshots)
## Contributing
Issues and PRs are welcome. See [AGENTS.md](AGENTS.md) for architecture and conventions; it is written for both human contributors and coding agents.
## License
[MIT](LICENSE)
