# PagePixels Screenshots MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [PagePixels](https://pagepixels.com) Screenshot API. Enables AI assistants to capture instant and scheduled screenshots, generate images from custom HTML, take screenshots after performing browser actions, and fetch the full raw HTML from dynamic websites using natural language.

## Features

- **Instant Screenshots** — Capture any URL or render raw HTML to an image on demand
- **Multi-Step Browser Actions** — Click, type, submit forms, navigate pages, and wait for elements before capturing
- **Scheduled Screenshots** — Create recurring capture configurations on minute, hour, day, week, month, or year intervals
- **Real Location Screenshots** — Screenshot from 150+ geographical locations (countries, US states, and major cities)
- **AI Analysis Screenshots** — Capture screenshots and have AI analyze the images guided by custom text prompts
- **Custom HTML Screenshots** — Create screenshots from HTML and data available in the MCP client
- **Multiple Image AI Analysis** — Have AI compare up to 5 images and 5 prompts
- **Extract HTML** — Enable AI to get HTML content from dynamic websites that generate their HTML using JavaScript and find CSS Selectors
- **Full Configuration Management** — Create, read, update, delete, and list screenshot configurations programmatically
- **OAuth 2.1 Authentication** — Secure, spec-compliant MCP auth via Streamable HTTP transport

## Requirements

- A [PagePixels](https://pagepixels.com) account (free tier available — no payment info required)

## Quick Start

### MCP Server URL

Connect over Streamable HTTP by pointing your client at:

```
https://mcp.pagepixels.com/mcp
```

### Example: Claude.ai Web 

1. Open **Customize** (toolbox icon).
2. Select **Connectors**.
3. Click **Add**. Select **Add custom connector** option.
3. Enter the server URL:
   ```
   https://mcp.pagepixels.com/mcp
   ```
4. Complete the OAuth authorization when prompted in the browser.

Once connected, PagePixels tools will be available in all new conversations.

## Tools

### Capture Instant Screenshots

| Tool | Description |
|---|---|
| `snap` | Capture a screenshot of any URL with full control over viewport, format, quality, wait conditions, JS/CSS injection, multi-step browser actions, AI analysis, and geo-location. |
| `snap_html` | Render raw HTML content into a screenshot with the same capture options as the `snap` tool. |
| `capture_screenshot` | Trigger an immediate capture for an existing screenshot configuration. |

### Scheduled Screenshots

| Tool | Description |
|---|---|
| `create_screenshot_config` | Create a new screenshot configuration with optional interval scheduling (minutes, hours, days, months years). |
| `get_screenshot_config` | Retrieve a screenshot configuration by ID. |
| `update_screenshot_config` | Update any property of an existing screenshot configuration. |
| `delete_screenshot_config` | Delete a screenshot configuration and all its captured screenshots. |
| `list_screenshot_configs` | List all screenshot configurations in the account with pagination and time filters. |
| `get_job_status` | Check if a screenshot job has completed. |

### Screenshot History

| Tool | Description |
|---|---|
| `list_config_screenshots` | List all screenshots for a specific configuration. |
| `list_all_screenshots` | List all screenshots across the account. |

### Real Locations

| Tool | Description |
|---|---|
| `list_real_locations` | List all 150+ supported geo-locations for screenshot capture. |

### Multiple Image AI Analysis

| Tool | Description |
|---|---|
| `analyze_any_image_with_ai` | Submit up to 5 images and 5 prompts for an AI to analyze. |

### Extract HTML

| Tool | Description |
|---|---|
| `extract_html` | Fetch raw HTML content from a URL. Useful for dynamically loaded websites. |

### Change Notifications

| Tool | Description |
|---|---|
| `list_config_change_notifications` | List change notifications for a specific configuration. |
| `list_all_change_notifications` | List all change notifications across the account. |

### Account

| Tool | Description |
|---|---|
| `get_account_limits` | Get current usage and account limits. |

## Usage Examples

Once connected, interact naturally with your AI assistant:

**Take a screenshot:**
> "Take a screenshot of https://example.com in PNG format at 540px wide and remove cookie banners"

**Multi-step capture:**
> "Go to https://example.com, fill in the search field with 'text to search for', submit the form, then take a full-page screenshot"

**Scheduled monitoring:**
> "Capture a screenshot of https://example.com/pricing every 6 hours"

**Geo-located capture:**
> "Screenshot https://example.com from Japan and wait 6000ms before taking the screenshot"

**Fetch HTML content:**
> "Extract the HTML content from https://example.com with PagePixels and check for spelling and grammatical errors"

**Account overview:**
> "Show me my current usage and remaining credits for PagePixels"

## Capture Options

The `snap` and `snap_html` tools support extensive configuration:

- **Viewport:** `page_width`, `page_height`, `scale_factor` (1x or 2x Retina)
- **Output:** `image_format` (jpeg, png, webp, pdf), `quality` (1–100 for JPEG), thumbnails
- **Full Page:** `fullpage`, `fullpage_advanced`, `incremental_scroll` for lazy-loaded content
- **Element Capture:** `selectors` to screenshot a specific DOM element
- **Timing:** `wait` (ms delay before capture), `wait_for` (CSS selector to appear)
- **Custom Styles:** `css_inject`
- **Scripting:** `js_inject`
- **Remove/disable:** `no_ads`, `no_cookie_banners`, `no_tracking`
- **Geo-Location:** `real_location` (150+ locations), `time_zone`, `accept_language`
- **AI Analysis:** `analyze_image_with_ai` and `ai_prompt` to analyze a screenshot guided by a custom text prompt
- **Auth & headers:** `cookies`, `headers`, `user_agent`
- **Caching:** `ttl` to control cache duration (0 for always fresh)

[See full list of screenshot options](https://pagepixels.com/app/screenshots-api-documentation#api-options).

## Multi-Step Actions

Automate browser interactions before capturing with `multi_step_actions`:

```json
[
  { "type": "wait_for_selector", "selector": "#email" }
  { "type": "text_field", "selector": "#email", "value": "user@example.com" },
  { "type": "text_field", "selector": "#password", "value": "secret" },
  { "type": "submit" },
  { "type": "wait", "value": "8000" },
  { "type": "click", "selector": ".chart-filter" }
]
```

Supported action types: `click`, `hover`, `change`, `redirect`, `javascript`, `evaluateJs`, `css`, `text_field`, `select`, `checkbox`, `submit`, `wait`, `wait_for_selector`

[See Multi-Step section of MCP Help Guide](https://pagepixels.com/help/mcp#multi-step-actions)

## Authentication

Authentication is handled through the standard MCP OAuth 2.1 flow with PKCE and uses DCR (Dynamic Client Registration). When connecting through Claude.ai, ChatGPT, VS Code, or other OAuth-capable MCP clients, authorize through the browser prompt when first connecting. No manual API key configuration is needed.

For programmatic access outside of MCP, see the [PagePixels API documentation](https://pagepixels.com/app/documentation).

## Transport

This server uses the MCP Streamable HTTP transport, hosted at:

```
https://mcp.pagepixels.com/mcp
```

All MCP clients that support remote Streamable HTTP servers can connect directly. OAuth 2.1 with PKCE is enforced on all connections.

## Resources

- [Screenshot MCP Server Help Guide](https://pagepixels.com/help/mcp) — Guide to using the PagePixels MCP Server
- [PagePixels Documentation](https://pagepixels.com/app/documentation) — Full API reference
- [Model Context Protocol](https://modelcontextprotocol.io) — MCP specification

## Support

Contact PagePixels anytime by email: 

```
support-tickets@pagepixels.com
```

Or contact us through our [Support Form](https://pagepixels.com/support).

## License

MIT