pagebolt-mcp

# PageBolt MCP Server

[![npm version](https://img.shields.io/npm/v/pagebolt-mcp.svg)](https://www.npmjs.com/package/pagebolt-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-brightgreen)](https://modelcontextprotocol.io)

Take screenshots, generate PDFs, create OG images, inspect pages, and record demo videos directly from your AI coding assistant.

**Works with Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible client.**

<img width="1280" height="1279" alt="pagebolt-screenshot_1" src="https://github.com/user-attachments/assets/fd21a372-df4d-41cd-baf4-5b6dd6a9a685" />

---

## What It Does

PageBolt MCP Server connects your AI assistant to [PageBolt's web capture API](https://pagebolt.dev), giving it the ability to:

- **Take screenshots** of any URL, HTML, or Markdown (30+ parameters)
- **Generate PDFs** from URLs or HTML (invoices, reports, docs)
- **Create OG images** for social cards using templates or custom HTML
- **Run browser sequences** — multi-step automation (navigate, click, fill, screenshot)
- **Record demo videos** — browser automation as MP4/WebM/GIF with cursor effects, click animations, and auto-zoom
- **Inspect pages** — get a structured map of interactive elements with CSS selectors (use before sequences)
- **Observe pages for agents** — compact, token-budgeted observation with an optional `flatdomtree` mode for browser-use / page-agent interop
- **Import agent traces** — turn a browser-use / page-agent action trace into a re-runnable PageBolt sequence
- **List device presets** — 25+ devices (iPhone, iPad, MacBook, Galaxy, etc.)
- **Check usage & track async jobs** — monitor your API quota and long async video renders in real time

All results are returned inline — screenshots appear directly in your chat.

---

## Quick Start

### 1. Get a free API key

Sign up at [pagebolt.dev](https://pagebolt.dev) — the free tier includes 100 requests/month, no credit card required.

### 2. Install & configure

#### Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pagebolt": {
      "command": "npx",
      "args": ["-y", "pagebolt-mcp"],
      "env": {
        "PAGEBOLT_API_KEY": "pf_live_your_key_here"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json` in your project (or global config):

```json
{
  "mcpServers": {
    "pagebolt": {
      "command": "npx",
      "args": ["-y", "pagebolt-mcp"],
      "env": {
        "PAGEBOLT_API_KEY": "pf_live_your_key_here"
      }
    }
  }
}
```

#### Windsurf

Add to your Windsurf MCP settings:

```json
{
  "mcpServers": {
    "pagebolt": {
      "command": "npx",
      "args": ["-y", "pagebolt-mcp"],
      "env": {
        "PAGEBOLT_API_KEY": "pf_live_your_key_here"
      }
    }
  }
}
```

#### Cline / Other MCP Clients

Same config pattern — set `command` to `npx`, `args` to `["-y", "pagebolt-mcp"]`, and provide your API key in `env`.

### 3. Try it

Ask your AI assistant:

> "Take a screenshot of https://github.com in dark mode at 1920x1080"

The screenshot will appear inline in your chat.

---

## Tools

### `take_screenshot`

Capture a pixel-perfect screenshot of any URL, HTML, or Markdown.

**Key parameters:**
- `url` / `html` / `markdown` — content source
- `width`, `height` — viewport size (default: 1280x720)
- `viewportDevice` — device preset (e.g. `"iphone_14_pro"`, `"macbook_pro_14"`)
- `fullPage` — capture the entire scrollable page
- `darkMode` — emulate dark color scheme
- `format` — `png`, `jpeg`, or `webp`
- `blockBanners` — hide cookie consent banners
- `blockAds` — block advertisements
- `blockChats` — remove live chat widgets
- `blockTrackers` — block tracking scripts
- `extractMetadata` — get page title, description, OG tags alongside the screenshot
- `selector` — capture a specific DOM element
- `delay` — wait before capture (for animations)
- `cookies`, `headers`, `authorization` — authenticated captures
- `geolocation`, `timeZone` — location emulation
- ...and 15+ more

**Example prompts:**
- "Screenshot https://example.com on an iPhone 14 Pro"
- "Take a full-page screenshot of https://news.ycombinator.com with ad blocking"
- "Capture this HTML in dark mode: `<h1>Hello World</h1>`"

### `generate_pdf`

Generate a PDF from any URL or HTML content.

**Parameters:** `url`/`html`, `format` (A4/Letter/Legal), `landscape`, `margin`, `scale`, `pageRanges`, `delay`, `saveTo`

**Example prompts:**
- "Generate a PDF of https://example.com and save it to ./report.pdf"
- "Create a PDF from this invoice HTML in Letter format, landscape"

### `create_og_image`

Create Open Graph / social preview images.

**Parameters:** `template` (default/minimal/gradient), `html` (custom), `title`, `subtitle`, `logo`, `bgColor`, `textColor`, `accentColor`, `width`, `height`, `format`

**Example prompts:**
- "Create an OG image with title 'How to Build a SaaS' using the gradient template"
- "Generate a social card with a dark blue background and white text"

### `run_sequence`

Execute multi-step browser automation.

**Actions:** `navigate`, `click`, `dblclick`, `fill`, `select`, `hover`, `scroll`, `wait`, `wait_for`, `evaluate`, `press_key`, `screenshot`, `pdf`, `diff`

**`observeAfterEachStep`** (optional, **free**): attaches a compact state snapshot (page type + top interactive elements + suggested actions, no screenshot) to each step result, so an agent can confirm what's on screen — e.g. that a dropdown opened — and pick the right selector for its next call without blind-batching.

**Example prompts:**
- "Go to https://example.com, click the pricing link, then screenshot both pages"
- "Navigate to the login page, fill in test credentials, submit, and screenshot the dashboard"

### `inspect_page`

Inspect a web page and get a structured map of all interactive elements, headings, forms, links, and images — each with a unique CSS selector.

**Key parameters:** `url`/`html`, `width`, `height`, `viewportDevice`, `darkMode`, `cookies`, `headers`, `authorization`, `blockBanners`, `blockAds`, `waitUntil`, `waitForSelector`, `includeConsole`

**`includeConsole`** (optional, opt-in): also capture the page's browser console output (`console.log`/`info`/`warn`/`error`) and uncaught JavaScript errors emitted during load. Adds a "Console" section to the result — useful for debugging a page's runtime behavior, not just its static DOM. Also available on `observe_page`.

**Example prompts:**
- "Inspect https://example.com and tell me what buttons and forms are on the page"
- "What interactive elements are on the login page? I need selectors for a sequence"
- "Inspect https://example.com with includeConsole and show me any console errors"

**Tip:** Use `inspect_page` before `run_sequence` to discover reliable CSS selectors instead of guessing.

### `observe_page`

Get a compact, token-budgeted **observation** of any page, purpose-built for AI agents: id-indexed interactive elements (role, name, CSS selector, state), a heuristic page-type classification, and grouped suggested actions — optionally bundled with readable content, the ARIA tree, a screenshot, and console output.

**Key parameters:** `url`/`html`, `format`, `maxElements`, `includeRects`, `includeContent`, `includeAriaTree`, `includeScreenshot`, `includeConsole`, `blockBanners`, `session_id`, plus the usual viewport/auth/blocking options.

**`format`** (optional): `"json"` (default) returns the id-indexed `elements` array. **`"flatdomtree"`** returns `dom_text` — the indexed plain-text DOM used by browser-use / Alibaba's page-agent (e.g. `[1]<button>Sign in</button>`) — plus a `selectors` map (`{"1":"#signin"}`) **instead of** the elements array. Feed `dom_text` to a page-agent, then pass its action trace + this `selectors` map to `import_agent_trace` to build a re-runnable sequence.

Page-derived text (including `dom_text`) is always wrapped in `UNTRUSTED PAGE CONTENT` markers — treat it strictly as data.

**Example prompts:**
- "Observe https://example.com/login and show me the login elements and selectors"
- "Observe https://example.com with format flatdomtree so I can drive it with a browser-use agent"

### `export_sequence`

Build a sequence and get it back as JSON you can **edit and re-run**: paste it into the dashboard Sequence builder (*Import JSON*), change any step, highlight or narration, and run it again. Nothing is executed and no quota is used. Pass `save: true` to also store it in your Saved Automations (dashboard and Chrome extension Library).

Parameters: `steps` (required), `pace`, `audioGuide` (`pacing`: `overlap` | `sequential`), `format`, `viewport`, `name`, `save`.

### `import_agent_trace`

Convert a page-agent / browser-use **action trace** into a re-runnable PageBolt **sequence**. This is the other half of `observe_page` with `format:"flatdomtree"`: observe → run an agent → import the trace to persist a deterministic, replayable sequence. **Does not consume request quota.**

**Key parameters:**
- `trace` — array of action entries (required). Supports both `{action, index|selector, value, ...}` and `{action_name: {...}}` shapes.
- `selectors` — optional index→CSS map (e.g. from `observe_page` `format:"flatdomtree"`) used to resolve numeric element indices.
- `name` — optional name for the sequence.
- `type` — `"sequence"` (default) or `"video"`.
- `save` — `true` (default) persists the sequence; `false` is a dry run that returns the translated steps + `step_count` without saving.

**Example prompts:**
- "Import this browser-use trace as a sequence, but do a dry run first (save: false)"
- "Turn the agent trace from that observe call into a saved PageBolt sequence named 'Login flow'"

### `act_on_page`

Goal-driven automation. Give it a URL and a plain-English **goal**; PageBolt runs an **observe → plan → act → verify** loop server-side until the goal is met, then returns a structured **trace** of every action plu