# Set up ezscreenshots MCP

**Give this page to your AI agent.** Ask it to add the ezscreenshots MCP server to your editor (Cursor, Claude Code, Codex, etc.) and walk you through Pro auth.

**Requires:** [ezscreenshots Pro](https://ezscreenshots.com/app) ($39/year). Rendering runs on ezscreenshots servers — you do not host anything.

---

## 1. Install the MCP server

Run once on the user's machine:

```bash
npm install -g @ezscreenshots/mcp@0.1.2
```

If `ezscreenshots-mcp` is not on PATH, use the full path from `which ezscreenshots-mcp` after install.

---

## 2. Add to MCP config

**Cursor** — merge into `~/.cursor/mcp.json` (or Cursor Settings → MCP):

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

**Claude Code / Claude Desktop** — add the same `mcpServers` block to that tool's MCP config (e.g. Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS).

**Codex** — add the same block to your Codex MCP settings file for your environment.

Restart the editor after saving. Toggle the `ezscreenshots` server on if needed.

---

## 3. Connect Pro (device auth)

After the MCP server is running, the agent should:

1. Call **`ez_connect`** → give the user the `verification_url`.
2. **User** opens that URL in Chrome/Safari (their normal browser — **not** the IDE's built-in browser). Same machine where they use [ezscreenshots](https://ezscreenshots.com/app) with Pro.
3. User clicks **Authorize** on the connect page.
4. Agent calls **`ez_connect_poll`** once the user confirms.

Token is saved locally at `~/.config/ezscreenshots/credentials.json`.

---

## 4. Render a screenshot

Agent calls **`ez_render_screenshot`** with a job JSON. Example shape:

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

`screens[0].image` is required (PNG as data URL or raw base64). Use **`ez_list_presets`** for sizes and fields.

---

## Tools

| Tool | Purpose |
|------|---------|
| `ez_connect` | Start Pro auth — returns link for user |
| `ez_connect_poll` | Finish auth after user authorizes |
| `ez_validate_token` | Check if already connected |
| `ez_list_presets` | Device sizes + job schema |
| `ez_render_screenshot` | Render PNG (Pro, after auth) |

---

## Troubleshooting

- **`ezscreenshots-mcp: command not found`** — Use global install above; avoid `npx` from inside the `packages/mcp` dev folder.
- **`ENOENT` under `~/.npm/_npx`** — Run `rm -rf ~/.npm/_npx` and prefer global install.
- **Auth fails** — User must open the connect link in their real browser where Pro is active, not an automated agent browser.

---

## Links

- Human overview: https://ezscreenshots.com/mcp/
- npm: https://www.npmjs.com/package/@ezscreenshots/mcp
- Pro / editor: https://ezscreenshots.com/app