@ezscreenshots/mcp

stdio MCP server for ezscreenshots Pro — generate App Store / Play Store screenshot PNGs from your AI agent.

Rendering runs on ezscreenshots infrastructure (Cloudflare Browser Run). This package is a thin local client: no server to host.

Tools

| Tool | Description | |------|-------------| | ez_connect | Start auth — returns verification_url for the user | | ez_connect_poll | After user clicks Authorize, saves API token | | ez_validate_token | Is a token saved? If not, points to ez_connect | | ez_list_presets | Canvas sizes + job JSON shape | | ez_render_screenshot | Render job → PNG (requires auth first) |

Auth (device connect)

The agent must not open the connect URL in an automated/IDE browser. Pro lives in the user’s normal browser (localStorage on the machine where they use /app).

1. Agent calls ez_connect → copy verification_url to the user.
2. User opens that link in Chrome/Safari (same device as their Pro purchase / usual ezscreenshots use).
3. User clicks Authorize on /connect.
4. Agent calls ez_connect_poll (after user says they’re done).

ez_validate_token only checks local config — it does not start connect. If configured: false, run ez_connect next (do not improvise shell fetch loops or browser MCP).

Token storage:

• Env: EZSCREENSHOTS_API_TOKEN=ez_api_… (skips device flow)
• File: ~/.config/ezscreenshots/credentials.json (written after device connect)

Cursor config

Recommended — install once globally (avoids broken npx cache and cwd quirks):

npm install -g @ezscreenshots/[email protected]

{
  "mcpServers": {
    "ezscreenshots": {
      "command": "ezscreenshots-mcp",
      "env": {
        "EZSCREENSHOTS_API_BASE": "https://ezscreenshots.com"
      }
    }
  }
}

If Cursor cannot find the binary, use the full path from which ezscreenshots-mcp.

Alternative — npx (run from your home dir or project root, not from packages/mcp in this repo — same package name confuses npm):

{
  "mcpServers": {
    "ezscreenshots": {
      "command": "npx",
      "args": ["-y", "@ezscreenshots/[email protected]"],
      "env": {
        "EZSCREENSHOTS_API_BASE": "https://ezscreenshots.com"
      }
    }
  }
}

Or pin the bin explicitly:

"args": ["-y", "--package", "@ezscreenshots/[email protected]", "ezscreenshots-mcp"]

Troubleshooting

| Error | Fix | |-------|-----| | ENOENT … ~/.npm/_npx/.../package.json | rm -rf ~/.npm/_npx, restart Cursor | | sh: ezscreenshots-mcp: command not found | Use global install above, or run npx outside packages/mcp | | Still failing | "command": "node", "args": ["/full/path/to/.../node_modules/@ezscreenshots/mcp/bin/cli.js"] after npm i -g |

Local development (this repo):

{
  "mcpServers": {
    "ezscreenshots": {
      "command": "node",
      "args": ["/absolute/path/to/ezscreenshots/packages/mcp/src/index.js"]
    }
  }
}

Suggested agent flow

ez_validate_token  →  if not configured: ez_connect
(tell user to open verification_url in their browser)
(user authorizes)
ez_connect_poll    →  ez_render_screenshot

Example job

{
  "preset": "iphone-6.9",
  "theme": {
    "bg": "#2e1064",
    "accent": "#e879f9",
    "font": "Geist",
    "deviceFrame": true,
    "density": "tight",
    "gradient": { "c1": "#2e1064", "c2": "#7c3aed", "angle": 160 }
  },
  "screens": [{
    "image": "data:image/png;base64,...",
    "caption": "Your week at a *glance*",
    "subtitle": ""
  }]
}

screens[0].image is required (data URL or base64). Caption markup: *bold*, ***bold italic***.

Environment

| Variable | Default | |----------|---------| | EZSCREENSHOTS_API_BASE | https://ezscreenshots.com | | EZSCREENSHOTS_API_TOKEN | — (optional; bypasses device connect) |

License

Proprietary — see LICENSE. No permission to copy, modify, or redistribute this package without written consent from the copyright holder.