{
"markdown": "# PageBolt MCP Server\n\n[](https://www.npmjs.com/package/pagebolt-mcp)\n[](https://opensource.org/licenses/MIT)\n[](https://modelcontextprotocol.io)\n\nTake screenshots, generate PDFs, create OG images, inspect pages, and record demo videos directly from your AI coding assistant.\n\n**Works with Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible client.**\n\n\n\n---\n\n## What It Does\n\nPageBolt MCP Server connects your AI assistant to [PageBolt's web capture API](https://pagebolt.dev), giving it the ability to:\n\n- **Take screenshots** of any URL, HTML, or Markdown (30+ parameters)\n- **Generate PDFs** from URLs or HTML (invoices, reports, docs)\n- **Create OG images** for social cards using templates or custom HTML\n- **Run browser sequences** — multi-step automation (navigate, click, fill, screenshot)\n- **Record demo videos** — browser automation as MP4/WebM/GIF with cursor effects, click animations, and auto-zoom\n- **Inspect pages** — get a structured map of interactive elements with CSS selectors (use before sequences)\n- **Observe pages for agents** — compact, token-budgeted observation with an optional `flatdomtree` mode for browser-use / page-agent interop\n- **Import agent traces** — turn a browser-use / page-agent action trace into a re-runnable PageBolt sequence\n- **List device presets** — 25+ devices (iPhone, iPad, MacBook, Galaxy, etc.)\n- **Check usage & track async jobs** — monitor your API quota and long async video renders in real time\n\nAll results are returned inline — screenshots appear directly in your chat.\n\n---\n\n## Quick Start\n\n### 1. Get a free API key\n\nSign up at [pagebolt.dev](https://pagebolt.dev) — the free tier includes 100 requests/month, no credit card required.\n\n### 2. Install & configure\n\n#### Claude Desktop\n\nAdd to `~/.claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pagebolt\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"pagebolt-mcp\"],\n \"env\": {\n \"PAGEBOLT_API_KEY\": \"pf_live_your_key_here\"\n }\n }\n }\n}\n```\n\n#### Cursor\n\nAdd to `.cursor/mcp.json` in your project (or global config):\n\n```json\n{\n \"mcpServers\": {\n \"pagebolt\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"pagebolt-mcp\"],\n \"env\": {\n \"PAGEBOLT_API_KEY\": \"pf_live_your_key_here\"\n }\n }\n }\n}\n```\n\n#### Windsurf\n\nAdd to your Windsurf MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"pagebolt\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"pagebolt-mcp\"],\n \"env\": {\n \"PAGEBOLT_API_KEY\": \"pf_live_your_key_here\"\n }\n }\n }\n}\n```\n\n#### Cline / Other MCP Clients\n\nSame config pattern — set `command` to `npx`, `args` to `[\"-y\", \"pagebolt-mcp\"]`, and provide your API key in `env`.\n\n### 3. Try it\n\nAsk your AI assistant:\n\n> \"Take a screenshot of https://github.com in dark mode at 1920x1080\"\n\nThe screenshot will appear inline in your chat.\n\n---\n\n## Tools\n\n### `take_screenshot`\n\nCapture a pixel-perfect screenshot of any URL, HTML, or Markdown.\n\n**Key parameters:**\n- `url` / `html` / `markdown` — content source\n- `width`, `height` — viewport size (default: 1280x720)\n- `viewportDevice` — device preset (e.g. `\"iphone_14_pro\"`, `\"macbook_pro_14\"`)\n- `fullPage` — capture the entire scrollable page\n- `darkMode` — emulate dark color scheme\n- `format` — `png`, `jpeg`, or `webp`\n- `blockBanners` — hide cookie consent banners\n- `blockAds` — block advertisements\n- `blockChats` — remove live chat widgets\n- `blockTrackers` — block tracking scripts\n- `extractMetadata` — get page title, description, OG tags alongside the screenshot\n- `selector` — capture a specific DOM element\n- `delay` — wait before capture (for animations)\n- `cookies`, `headers`, `authorization` — authenticated captures\n- `geolocation`, `timeZone` — location emulation\n- ...and 15+ more\n\n**Example prompts:**\n- \"Screenshot https://example.com on an iPhone 14 Pro\"\n- \"Take a full-page screenshot of https://news.ycombinator.com with ad blocking\"\n- \"Capture this HTML in dark mode: `
Hello World
`\"\n\n### `generate_pdf`\n\nGenerate a PDF from any URL or HTML content.\n\n**Parameters:** `url`/`html`, `format` (A4/Letter/Legal), `landscape`, `margin`, `scale`, `pageRanges`, `delay`, `saveTo`\n\n**Example prompts:**\n- \"Generate a PDF of https://example.com and save it to ./report.pdf\"\n- \"Create a PDF from this invoice HTML in Letter format, landscape\"\n\n### `create_og_image`\n\nCreate Open Graph / social preview images.\n\n**Parameters:** `template` (default/minimal/gradient), `html` (custom), `title`, `subtitle`, `logo`, `bgColor`, `textColor`, `accentColor`, `width`, `height`, `format`\n\n**Example prompts:**\n- \"Create an OG image with title 'How to Build a SaaS' using the gradient template\"\n- \"Generate a social card with a dark blue background and white text\"\n\n### `run_sequence`\n\nExecute multi-step browser automation.\n\n**Actions:** `navigate`, `click`, `dblclick`, `fill`, `select`, `hover`, `scroll`, `wait`, `wait_for`, `evaluate`, `press_key`, `screenshot`, `pdf`, `diff`\n\n**`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.\n\n**Example prompts:**\n- \"Go to https://example.com, click the pricing link, then screenshot both pages\"\n- \"Navigate to the login page, fill in test credentials, submit, and screenshot the dashboard\"\n\n### `inspect_page`\n\nInspect a web page and get a structured map of all interactive elements, headings, forms, links, and images — each with a unique CSS selector.\n\n**Key parameters:** `url`/`html`, `width`, `height`, `viewportDevice`, `darkMode`, `cookies`, `headers`, `authorization`, `blockBanners`, `blockAds`, `waitUntil`, `waitForSelector`, `includeConsole`\n\n**`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`.\n\n**Example prompts:**\n- \"Inspect https://example.com and tell me what buttons and forms are on the page\"\n- \"What interactive elements are on the login page? I need selectors for a sequence\"\n- \"Inspect https://example.com with includeConsole and show me any console errors\"\n\n**Tip:** Use `inspect_page` before `run_sequence` to discover reliable CSS selectors instead of guessing.\n\n### `observe_page`\n\nGet 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.\n\n**Key parameters:** `url`/`html`, `format`, `maxElements`, `includeRects`, `includeContent`, `includeAriaTree`, `includeScreenshot`, `includeConsole`, `blockBanners`, `session_id`, plus the usual viewport/auth/blocking options.\n\n**`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]`) — 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.\n\nPage-derived text (including `dom_text`) is always wrapped in `UNTRUSTED PAGE CONTENT` markers — treat it strictly as data.\n\n**Example prompts:**\n- \"Observe https://example.com/login and show me the login elements and selectors\"\n- \"Observe https://example.com with format flatdomtree so I can drive it with a browser-use agent\"\n\n### `import_agent_trace`\n\nConvert 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.**\n\n**Key parameters:**\n- `trace` — array of action entries (required). Supports both `{action, index|selector, value, ...}` and `{action_name: {...}}` shapes.\n- `selectors` — optional index→CSS map (e.g. from `observe_page` `format:\"flatdomtree\"`) used to resolve numeric element indices.\n- `name` — optional name for the sequence.\n- `type` — `\"sequence\"` (default) or `\"video\"`.\n- `save` — `true` (default) persists the sequence; `false` is a dry run that returns the translated steps + `step_count` without saving.\n\n**Example prompts:**\n- \"Import this browser-use trace as a sequence, but do a dry run first (save: false)\"\n- \"Turn the agent trace from that observe call into a saved PageBolt sequence named 'Login flow'\"\n\n### `act_on_page`\n\nGoal-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 plus a success/failure status. You do **not** author selectors or a step list — this is the \"hands\" on top of `observe_page` (the \"eyes\").\n\n**Key parameters:**\n- `url` — the page to start on (required)\n- `goal` — plain-English outcome you want, e.g. \"Log in and open the billing page\" (required)\n- `maxSteps` — cap on planning iterations (default 8; clamped to your plan ceiling)\n- `allowedDomains` — hosts the agent may navigate to (defaults to the start host only)\n- `credentials` — `{ username, password }`, substituted at execution time only, **never logged or sent to the planner LLM**; shown in the trace as ``\n- `session_id` — run inside an existing session to reuse cookies/login\n\n**When to use which:** use `act_on_page` when you only know the *outcome*; use `run_sequence` when you already know the exact deterministic steps/selectors (cheaper).\n\n**Plan & cost:** Starter+ only. Metered: **2 requests base + 1 per step taken** (a 4-step run costs 6 requests).\n\n**Example prompts:**\n- \"On https://app.example.com/login, log in with these credentials and open the billing page\"\n- \"Go to https://example.com and accept the cookie banner, then start a free trial\"\n\n**Tip:** Scope `allowedDomains` tightly and avoid pointing it at destructive flows — the agent treats page text as untrusted and pursues only your goal.\n\n### `record_video`\n\nRecord a professional demo video of a multi-step browser automation sequence with cursor effects, click animations, smooth movement, and optional AI voice narration.\n\n**Key parameters:**\n- `steps` — same actions as `run_sequence` (except no screenshot/pdf — the whole sequence is the video)\n- `format` — `mp4`, `webm`, or `gif` (default: mp4; webm/gif require Starter+)\n- `framerate` — 24, 30, or 60 fps (default: 30)\n- `pace` — speed preset: `\"fast\"`, `\"normal\"`, `\"slow\"`, `\"dramatic\"`, `\"cinematic\"`, or a number 0.25–6.0\n- `cursor` — style (`highlight`/`circle`/`spotlight`/`dot`/`classic`), color, size, smoothing, persist\n- `clickEffect` — style (`ripple`/`pulse`/`ring`), color\n- `zoom` — auto-zoom on clicks with configurable level and duration\n- `frame` — browser chrome: `{ enabled: true, style: \"macos\" }` adds a macOS title bar\n- `background` — styled background: `{ enabled: true, type: \"gradient\", gradient: \"midnight\", padding: 40, borderRadius: 12 }`\n- `audioGuide` — AI voice narration: `{ enabled: true, script: \"Intro. {{1}} Step one. {{2}} Step two. Outro.\" }`\n- `darkMode` — emulate dark color scheme in the browser (recommended for light-background sites)\n- `blockBanners` — hide cookie consent popups (use on almost every recording)\n- `async` — render via an async job and poll to completion. Long recordings are enqueued (`202 { job_id }`) and this tool waits for the result, so they don't hit MCP client / API request timeouts. The async result is a **private hosted video URL** (its bytes can't be pulled back via the API key). Set `false` to force a single blocking synchronous request that returns the video **inline** (base64 embedded + saved to `saveTo`). **Default: `true`, except when you pass `saveTo`** (then the synchronous path is used so the file is actually produced on disk). Falls back to sync automatically if async is unavailable. **Quota is charged only on success; max 5 pending jobs per account.**\n- `pollTimeoutMs` — max time to wait for an async job (default: 240000 ≈ 4 min). If the render is still running when this elapses, the `job_id` is returned so you can check it later with `get_job`.\n- `saveTo` — output file path\n\n**Example prompts:**\n- \"Record a video of logging into https://example.com with a spotlight cursor\"\n- \"Make a narrated demo video of the signup flow at slow pace, save as demo.mp4\"\n- \"Record a demo of https://example.com with a macOS frame and midnight background\"\n\n---\n\n#### Best Practices for Polished Video Demos\n\n**1. Always inspect_page first**\n\nNever guess CSS selectors. Call `inspect_page` on the target URL before building your steps — it returns exact selectors for every button, input, and link. Guessed selectors like `button.primary` frequently miss; discovered selectors like `#radix-trigger-tab-dashboard` always hit.\n\n```\n1. inspect_page(url, { blockBanners: true })\n2. record_video(steps using selectors from step 1, ...)\n```\n\n**2. Use `live: true` on wait steps after clicks and navigations**\n\nAfter a click or navigate, content loads asynchronously. `live: false` (the default) freezes a single frame immediately — before anything renders. Set `live: true` on any wait step that follows an interaction so the video captures the actual page loading.\n\n```json\n{ \"action\": \"click\", \"selector\": \"#submit-btn\", \"note\": \"Submitting the form\" },\n{ \"action\": \"wait\", \"ms\": 2000, \"live\": true }\n```\n\n**3. Use `darkMode: true` for light-background sites**\n\nIf the target site has a white or very light background, it will clash with gradient/glass video backgrounds. Set `darkMode: true` to emulate `prefers-color-scheme: dark` — most modern sites adapt cleanly, and the result looks far more polished on screen.\n\n**4. Use `pace`, not wait steps, for timing**\n\n`pace` automatically inserts pauses between every step. Only use `wait` steps when the page genuinely needs load time (after navigation, after a click that triggers a fetch). Don't pad every transition with a wait — it creates dead air.\n\n| Use case | What to do |\n|----------|-----------|\n| Natural pacing between steps | Set `pace: \"slow\"` or `pace: \"dramatic\"` |\n| Page needs to load after click | `{ action: \"wait\", ms: 1500, live: true }` |\n| Hold on a view for narration | `{ action: \"wait\", ms: 3000, live: true }` |\n\n**5. Write an outro in the narration script**\n\nAudio is the master clock — the video trims or extends to match the TTS duration. Always end your `audioGuide.script` with a sentence after the last `{{N}}` marker. This prevents abrupt endings and gives the viewer a call to action.\n\n```json\n\"audioGuide\": {\n \"enabled\": true,\n \"script\": \"Welcome to PageBolt. {{1}} First, navigate to the dashboard. {{2}} Click on the export button. {{3}} Your report downloads instantly. Try it free at pagebolt.dev.\"\n}\n```\n\nThe text after `{{3}}` plays over the final frames as a clean outro. Without it, the audio ends mid-sequence and the remaining video plays in silence.\n\n**6. Add notes on every meaningful step**\n\nNotes render as styled tooltip overlays during playback. Add a `\"note\"` field on every action step except `wait`/`wait_for`. Keep them short (under 80 chars). They turn a raw browser recording into a guided tour.\n\n```json\n{ \"action\": \"navigate\", \"url\": \"https://example.com\", \"note\": \"Opening the dashboard\" },\n{ \"action\": \"click\", \"selector\": \"#export-btn\", \"note\": \"Click to export as PDF\" }\n```\n\n**7. Complete polished video example**\n\n```json\n{\n \"steps\": [\n { \"action\": \"navigate\", \"url\": \"https://app.example.com\", \"note\": \"Opening the app\" },\n { \"action\": \"wait\", \"ms\": 1500, \"live\": true },\n { \"action\": \"click\", \"selector\": \"#tab-reports\", \"note\": \"Switch to the Reports tab\" },\n { \"action\": \"wait\", \"ms\": 1200, \"live\": true },\n { \"action\": \"click\", \"selector\": \"#btn-export\", \"note\": \"Export the current report\" },\n { \"action\": \"wait\", \"ms\": 2000, \"live\": true },\n { \"action\": \"scroll\", \"y\": 400, \"note\": \"Scroll to see the full results\" }\n ],\n \"pace\": \"slow\",\n \"format\": \"mp4\",\n \"darkMode\": true,\n \"blockBanners\": true,\n \"frame\": { \"enabled\": true, \"style\": \"macos\", \"theme\": \"dark\" },\n \"background\": { \"enabled\": true, \"type\": \"gradient\", \"gradient\": \"midnight\", \"padding\": 40, \"borderRadius\": 12 },\n \"cursor\": { \"style\": \"classic\", \"visible\": true, \"persist\": true },\n \"clickEffect\": { \"style\": \"ripple\" },\n \"audioGuide\": {\n \"enabled\": true,\n \"script\": \"Here's how the export flow works. {{1}} Open the app and navigate to the dashboard. {{2}} Switch to the Reports tab. {{3}} Click Export. {{4}} Your report is ready in seconds. Try it free at example.com.\"\n }\n}\n```\n\n### `list_devices`\n\nList all 25+ available device presets with viewport dimensions.\n\n**Example prompt:**\n- \"What device presets are available for screenshots?\"\n\n### `check_usage`\n\nCheck your current API usage and plan limits.\n\n**Example prompt:**\n- \"How many API requests do I have left this month?\"\n\n### `list_jobs`\n\nList your recent async jobs (e.g. videos enqueued with `record_video`). Returns each job's id, type, status, and timestamps. **Free** (no request quota).\n\n**Example prompt:**\n- \"List my recent async video jobs and their status\"\n\n### `get_job`\n\nFetch the status and output of a single async job by id. While pending/processing it returns the current status; when completed it returns the output — for videos, the hosted watch/embed/file URLs. **Free** (no request quota).\n\n**Key parameter:** `job_id`\n\n**Example prompt:**\n- \"Check the status of video job abc123\"\n\n---\n\n## Prompts\n\nPre-built prompt templates for common workflows. In clients that support MCP prompts, these appear as slash commands.\n\n### `/capture-page`\n\nCapture a clean screenshot of any URL with sensible defaults (blocks banners, ads, chats, trackers).\n\n**Arguments:** `url` (required), `device`, `dark_mode`, `full_page`\n\n### `/record-demo`\n\nRecord a professional demo video. The agent inspects the page first to discover selectors, then builds a video recording sequence.\n\n**Arguments:** `url` (required), `description` (required — what the demo should show), `pace`, `format`\n\n### `/audit-page`\n\nInspect a page and get a structured analysis of its elements, forms, links, headings, and potential issues.\n\n**Arguments:** `url` (required)\n\n### `/capture-authenticated`\n\nCapture a page behind a login using the [auth.md](https://workos.com/auth.md) discovery pattern: find the target's auth metadata, obtain a credential on the user's behalf, then hand it to PageBolt via `authorization`/`cookies`/`headers`. Includes a built-in reality check — auth.md grants **API tokens, not browser session cookies**, so cookie-session web apps still need a real session cookie (which the prompt guides the agent to request).\n\n**Arguments:** `url` (required), `capture` (`observe`|`screenshot`), `credential`, `credential_type` (`bearer`|`cookie`|`header`)\n\n---\n\n## Resources\n\n### `pagebolt://api-docs`\n\nThe full PageBolt API reference as a text resource. AI agents that support MCP resources can read this for detailed parameter documentation beyond what fits in tool descriptions. Content is fetched from the live `llms-full.txt` endpoint.\n\n---\n\n## Configuration\n\n| Environment Variable | Required | Default | Description |\n|---------------------|----------|---------|-------------|\n| `PAGEBOLT_API_KEY` | **Yes** | — | Your PageBolt API key ([get one free](https://pagebolt.dev)) |\n| `PAGEBOLT_BASE_URL` | No | `https://pagebolt.dev` | API base URL |\n\n---\n\n## Pricing\n\n| Plan | Price | Requests/mo | Rate Limit |\n|------|-------|-------------|------------|\n| **Free** | $0 | 100 | 10 req/min |\n| Starter | $29/mo | 5,000 | 60 req/min |\n| Growth | $79/mo | 25,000 | 120 req/min |\n| Scale | $199/mo | 100,000 | 300 req/min |\n\nFree plan requires no credit card. Starter and Growth include a 14-day free trial.\n\n---\n\n## Why PageBolt?\n\n- **6 APIs, one key** — screenshot, PDF, OG image, browser automation, video recording, page inspection. Stop paying for separate tools.\n- **Clean captures** — automatic ad blocking, cookie banner removal, chat widget suppression, tracker blocking.\n- **25+ device presets** — iPhone SE to Galaxy S24 Ultra, iPad Pro, MacBook, Desktop 4K.\n- **Ship in 5 minutes** — plain HTTP, no SDKs required, works in any language.\n- **Inline results** — screenshots and OG images appear directly in your AI chat.\n\n---\n\n## Links\n\n- **Website:** [pagebolt.dev](https://pagebolt.dev)\n- **API Docs:** [pagebolt.dev/docs.html](https://pagebolt.dev/docs.html)\n- **npm:** [npmjs.com/package/pagebolt-mcp](https://www.npmjs.com/package/pagebolt-mcp)\n- **Issues:** [github.com/Custodia-Admin/pagebolt-mcp/issues](https://github.com/Custodia-Admin/pagebolt-mcp/issues)\n\n---\n\n## License\n\nMIT\n",
"bytes": 21525,
"sha": "e2b418b1b78b550c569514079e740a4f8b93a2e82f3a60270bc9a1ea1e15a2e6",
"repo_slug": "custodia-admin/pagebolt-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_custodia_admin_pagebolt_1b278193/readme"
}