Shipshots MCP Server

shipshots-mcp lets MCP-compatible agents create and improve Shipshots projects through the Shipshots API.

Agents can use it to build App Store screenshots, Play Store screenshots, social carousels, paid ads, launch graphics, and preview/export assets while the user keeps final control in the Shipshots web editor.

Quick Setup

npx shipshots-mcp init --token sb_your_token_here

Get a token from Shipshots at:

Dashboard -> Setup MCP

or:

Dashboard -> Settings -> MCP Tokens

Setup Options

npx shipshots-mcp init --token sb_... --client claude-code
npx shipshots-mcp init --token sb_... --client claude-desktop
npx shipshots-mcp init --token sb_... --client cursor
npx shipshots-mcp init --token sb_... --client stdout
npx shipshots-mcp init --token sb_... --url http://localhost:3000

Use --url http://localhost:3000 for local development.

Manual MCP Config

{
  "mcpServers": {
    "shipshots": {
      "command": "npx",
      "args": ["-y", "shipshots-mcp"],
      "env": {
        "SHIPSHOTS_API_URL": "https://shipshots.app",
        "SHIPSHOTS_API_TOKEN": "sb_your_token_here"
      }
    }
  }
}

Config locations vary by client:

• Claude Code: .mcp.json in the current project
• Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop Windows: %APPDATA%/Claude/claude_desktop_config.json
• Cursor: .cursor/mcp.json

Local Development

Start the app and render worker from the repository root:

make local

Then point the MCP server at the local app:

{
  "mcpServers": {
    "shipshots_local": {
      "command": "node",
      "args": ["/absolute/path/to/screenshotbuilder/packages/mcp/dist/index.js"],
      "env": {
        "SHIPSHOTS_API_URL": "http://localhost:3000",
        "SHIPSHOTS_API_TOKEN": "sb_local_user_token"
      }
    }
  }
}

Build the MCP package after code changes:

cd packages/mcp
pnpm run build
pnpm test

When both local and production MCP servers are configured, ask the agent to call start_design_workflow or get_server_info first. The response identifies whether the server writes to local development, production, or a custom API.

Recommended Agent Workflow

For new marketing work, agents should start with the workflow tools rather than jumping directly into primitive layer calls:

1. start_design_workflow
2. plan_marketing_campaign
3. suggest_creative_directions
4. create_marketing_project or set_marketing_mode
5. Layer/component creation and screenshot upload
6. run_quality_pass
7. audit_marketing_quality
8. Thumbnail or screen preview
9. Export or hand off the editor URL

This keeps the asset mode-aware. A social carousel, paid ad, and App Store screenshot set should not be judged by the same panel-count and CTA rules.

Marketing Modes

| Mode | Panel range | Device required | Notes | | --- | ---: | --- | --- | | app_store | 5-10 | Yes | App Store screenshot arc | | play_store | 2-8 | Yes | Google Play screenshot arc | | social_carousel | 3-10 | No | Swipeable social/LinkedIn/Instagram carousel | | paid_ad | 1-3 | No | Claim, proof, CTA | | launch_graphic | 1-5 | No | Product launch or announcement graphics |

Campaign metadata is stored on project.campaign. Screen roles are stored on screen.marketingRole.

Tool Groups

Workflow and Marketing

• start_design_workflow - returns server target, supported modes, guardrails, and current project context
• set_marketing_mode - persists campaign metadata on an existing project
• plan_marketing_campaign - suggests panel roles and copy structure
• suggest_creative_directions - returns creative directions such as safe store, bold carousel, or premium editorial
• create_marketing_project - creates a generic mode-aware project with starter screens and optional screenshots
• audit_marketing_quality - runs mode-aware marketing review plus layout quality context

Project Management

• create_project
• get_project
• delete_project
• list_projects
• list_templates
• get_project_url
• get_server_info

Screen Management

• add_screen
• update_screen
• remove_screen
• duplicate_screen
• connect_screens
• reorder_screens

Layer Management

• add_text_layer
• add_device_frame_layer
• add_image_layer
• add_shape_layer
• add_badge_layer
• add_arrow_layer
• update_layer
• remove_layer
• duplicate_layer
• move_layer
• reorder_layers
• align_layer
• align_layers
• upload_screenshot

Grouped Marketing Components

These tools create flat shape+text layers with shared component metadata:

• add_button_component
• add_pill_component
• add_callout_component
• add_proof_chip_component
• add_rating_component
• add_feature_tag_component
• update_component
• remove_component

The validator understands same-component overlap, so text sitting on a button or pill is not treated like accidental overlap.

Layout, Quality, and Validation

• apply_layout
• validate_screen
• run_quality_pass

run_quality_pass has two modes:

• Check mode reports issues without changing the project.
• Fix mode applies deterministic geometry and contrast fixes only.

The quality pass checks clipping, text/device overlap, poor spacing, low contrast, and connected-strip bounds. It understands intentional carousel bleed.

Install Campaigns (Admin Dogfood)

• plan_install_campaign
• upload_campaign_asset
• save_install_campaign
• render_campaign_pack
• get_campaign
• get_campaign_pack
• record_campaign_result

The install-campaign workflow turns portrait app recordings into a fixed pack of English and Thai TikTok/Meta creative: three concepts, two hooks each, a 9:16 narrated video and dedicated 4:5 and 1:1 posters per variant. Rendering is asynchronous; poll with get_campaign and retrieve the private ZIP with get_campaign_pack.

Batch Operations

• batch_add_layers
• batch_update_layers
• batch_remove_layers

Video

• update_video_config
• list_video_presets

Export and Preview

• get_screen_preview
• get_strip_preview
• get_thumbnail_preview
• get_contact_sheet_preview
• export_screenshot
• export_marketing_bundle

Preview tools accept a scale where supported. Thumbnail-scale previews are useful for iteration because store screenshots and social carousels often fail at small sizes before they fail at full size.

get_contact_sheet_preview returns ordered thumbnail image outputs through MCP. It is not currently a single stitched image.

export_marketing_bundle returns MCP image outputs with suggested filenames. It is not currently a ZIP download from MCP.

Design Data

• list_fonts
• list_palettes
• list_gradients

Supported Export Sizes

App Store

| Display | Size | | --- | --- | | iPhone 6.9" | 1260 x 2736 | | iPhone 6.5" | 1242 x 2688 | | iPhone 6.3" | 1206 x 2622 | | iPhone 6.1" | 1170 x 2532 | | iPhone 5.5" | 1242 x 2208 | | iPad 13" | 2064 x 2752 | | iPad 12.9" | 2048 x 2732 | | iPad 11" | 1668 x 2388 |

Google Play

| Display | Size | | --- | --- | | Android Phone | 1080 x 1920 | | Android Pixel | 1080 x 2340 | | Android Galaxy | 1440 x 3200 | | Android 7" Tablet | 1200 x 1920 |

Social and Ads

| Output | Size | | --- | --- | | Social Square | 1080 x 1080 | | Social Portrait | 1080 x 1350 | | Social Story | 1080 x 1920 | | Ad Square | 1080 x 1080 | | Ad Story | 1080 x 1920 |

Example Prompts

Use the local Shipshots MCP server only. Call start_design_workflow first and confirm the target is local.

Create a 4-panel social carousel for this app. Plan the arc, suggest creative directions, create the project, run the quality pass, audit it as social_carousel, and show thumbnail previews.

Create an App Store screenshot set from these real screenshots. Use app_store mode, make a 5-panel hook/feature/proof/CTA arc, run quality fixes only if deterministic, and report remaining issues.

Audit this project as paid_ad, not app_store. Tell me what is weak before changing anything.

Environment Variables

| Variable | Required | Description | | --- | --- | --- | | SHIPSHOTS_API_URL | Yes | Shipshots instance URL, for example https://shipshots.app or http://localhost:3000 | | SHIPSHOTS_API_TOKEN | Yes | User API token from the dashboard |

Notes and Limits

• Free accounts are limited by the app's plan rules. Pro removes project and preview limits.
• Real app screenshots are still required for final App Store-grade output.
• The generic campaign workflow intentionally avoids hyper-specific app-vertical templates.
• Preview rendering depends on the app and render worker being reachable from the configured API.

License

MIT