# MCP server

> HTML version: https://storeshot.art/docs/mcp/

The StoreShot MCP server lets coding agents call StoreShot as tools: read the store rules, upload
raw screenshots from your disk, create a [screenshot set](/docs/screenshot-sets/), follow it and
save the images into your project, fastlane folders included. It runs on your machine (stdio) and
needs Node 18 or later. It is published on
[npm](https://www.npmjs.com/package/@draggable/storeshot-mcp) as `@draggable/storeshot-mcp` under
the Apache-2.0 licence, with its source on [GitHub](https://github.com/Draggable/storeshot-mcp).
Writing your own integration instead? Use the [TypeScript SDK](/docs/sdk/).

## Add it to your agent

<!-- doctest: covered-by=packages/mcp-server/test-stack/mcp.stack.test.mjs -->

```sh
claude mcp add storeshot -- npx -y @draggable/storeshot-mcp
```

Cursor (`.cursor/mcp.json`) and Windsurf (`~/.codeium/windsurf/mcp_config.json`):

```json
{ "mcpServers": { "storeshot": { "command": "npx", "args": ["-y", "@draggable/storeshot-mcp"] } } }
```

VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "storeshot": { "type": "stdio", "command": "npx", "args": ["-y", "@draggable/storeshot-mcp"] }
  }
}
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.storeshot]
command = "npx"
args = ["-y", "@draggable/storeshot-mcp"]
```

## Link your account

You do not need to copy an API key. The first tool call answers with a link and a code: open the
link, sign in to the developer console and approve. The server then receives a key of its own (see
[Authentication](/docs/authentication/)) and stores it in
`~/.config/storeshot/mcp-credentials.json`, readable only by you. To unlink, revoke the key in the
console and delete that file. You can also set `STORESHOT_API_KEY` in the server's environment.

## Test and live keys

Test keys never spend credits and return sample images of the exact store sizes
([Test mode](/docs/test-mode/)); live keys make the real images and spend credits:
`generate_screenshot` costs 1 credit and `create_screenshot_set` 1 credit per image (ask for a quote
with `dryRun: true` first). Set `STORESHOT_ENVIRONMENT` to `test` or `live` before linking to choose
the key's environment; the console shows it before you approve.

## Tools

| Tool                     | What it does                                                  | Credits                 |
| ------------------------ | ------------------------------------------------------------- | ----------------------- |
| `get_store_requirements` | Screenshot rules of the App Store and Google Play             | free                    |
| `list_devices`           | Output sizes and their device ids                             | free                    |
| `upload_screenshot`      | Uploads a local PNG, JPEG or WebP screenshot                  | free                    |
| `generate_screenshot`    | One image for one size                                        | 1 (live keys)           |
| `create_screenshot_set`  | A whole listing in one job; `dryRun` quotes                   | 1 per image (live keys) |
| `get_job_status`         | Status of a generation or a set, with optional waiting        | free                    |
| `download_results`       | Saves the images into a folder (`store` or `fastlane` layout) | free                    |
| `get_credits`            | Your credit balance                                           | free                    |
| `link_status`            | Whether the server is linked, or the link to approve          | free                    |

## Your files

The server reads only the image files your agent names, and only PNG, JPEG or WebP files leave your
machine. Downloads are written only inside the folder you ask for, never through symbolic links,
and never over existing files unless the agent passes `overwrite: true`. Set `STORESHOT_MCP_ROOT`
to your project folder to keep both inside it.