# 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

```bash
npx shipshots-mcp init --token sb_your_token_here
```

Get a token from Shipshots at:

```text
Dashboard -> Setup MCP
```

or:

```text
Dashboard -> Settings -> MCP Tokens
```

### Setup Options

```bash
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

```json
{
  "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:

```bash
make local
```

Then point the MCP server at the local app:

```json
{
  "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:

```bash
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

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

```text
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.
```

```text
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.
```

```text
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