screenspo-mcp

An MCP server that gives AI agents access to Screenspo, a curated library of real App Store listing screenshots. Search apps and individual frames by layout, palette, category, content, background, mode, and caption treatment, then pull the actual image into the agent's context.

The package ships a build-time index of 379 iOS apps and 4,379 ordered listing screenshots: 2,827 vision-tagged iPhone frames and 1,552 iPad frames. Screenshots are fetched on demand from Screenspo's public CDN, with Apple's source image as a fallback.

Install

Claude Code:

claude mcp add screenspo -- npx -y screenspo-mcp

Codex:

codex mcp add screenspo -- npx -y screenspo-mcp

Cursor and other stdio MCP clients:

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

Tools

| Tool | What it does | | --- | --- | | get_design_vocabulary | Lists every supported filter with real example counts and explains filter semantics. | | search_apps | Finds comparable apps by product text, category, device, layout, color, mode, and listing content. | | search_screenshots | Searches individual iPhone and iPad listing frames and returns exact device/index pairs. | | get_app_details | Returns the palette, narrative, analysis, and complete device-specific ordered screenshot sets for one app. | | get_screenshot | Fetches the actual iPhone or iPad listing screenshot image for visual inspection. |

Recommended workflow

1. Call get_design_vocabulary to turn the brief into supported filters.
2. Use search_apps for comparable products and search_screenshots for specific visual treatments.
3. Read the ordered story with get_app_details.
4. Inspect the strongest frames with get_screenshot.
5. Deconstruct and recombine multiple references instead of copying one listing.

Screenspo covers App Store listing artwork. It does not provide evidence about in-app splash screens, login screens, or product UI flows.

Development

cd mcp
npm install
npm test
npm run build
npm run smoke

npm run build:data regenerates the compact published dataset from the website's canonical data/apps.json and data/tags.json files.