SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsmcp-page-capture

mcp-page-capture

Capture webpage screenshots, viewport or full-page, as base64 PNG.

Open website

About this tool

Purpose

mcp-page-capture is a Model Context Protocol (MCP) server that orchestrates headless Chromium via Puppeteer to take pixel-perfect screenshots of any URL and return MCP-compatible metadata for use in automated workflows. It targets Copilot/MCP-enabled environments and can be embedded in automation pipelines or run as a standalone developer tool.

Key capabilities

  • High-fidelity screenshots driven by Puppeteer and headless Chromium, supporting viewport screenshots and full-page screenshots.
  • LLM-optimized schema that exposes minimal parameters and provides sensible defaults.
  • Structured DOM extraction, with optional CSS selectors, for easy AI consumption.
  • Device presets for mobile emulation (iPhone, iPad, Android, desktop).
  • Six simplified steps for easy LLM use: viewport, wait, fill, click, scroll, screenshot.
  • Smart defaults: automatic screenshot when omitted, automatic field type detection.
  • Consistent parameter naming: target for elements, for for waiting, to for scrolling, device for viewport.
  • Automatic retries with exponential backoff on transient failures.
  • Telemetry hooks for centralized observability and monitoring.
  • Pluggable storage backends (local filesystem, S3, in-memory).
  • Structured logging and defensive error handling for operational visibility.
  • Can be started via npm start, npm run dev, or as a long-running MCP sidecar.
  • Provides multi-platform Docker images (amd64, arm64).

Usage

The MCP transport starts a Node.js server and registers the captureScreenshot and extractDom tools. Passed tool calls are validated against the relevant type definitions. Puppeteer launches (or reuses) a Chromium instance, navigates to the requested URL, and obtains a screenshot or serializes the DOM according to the tool parameters. The server returns structured content (images, text, DOM tree, metadata) to the caller or downstream workflow.

Running from source (recommended during development):

npm install
npm start

Run the server: for local iteration, run with hot reload npm run dev.

Docker build and run:

docker build -t mcp-page-capture .
docker run -p 3000:3000 mcp-page-capture

(Docker provides a consistent environment and can be deployed as a sidecar/service to Kubernetes, ECS, Fly.io, etc.)

IDE MCP configuration: you may need to use dist/cli.js or the full path to node, depending on the working directory and Node.js module resolution configuration.

Programmatic use: the server can be embedded in another Node.js process by importing the helper functions exposed by the package.

Six step types (exactly six)

Step order: automatically corrected! viewport is automatically moved to the first position, and screenshot is automatically added to the end.

  • viewport: sets the viewport or device preset.
  • wait: waits. The parameter for is used for the wait condition, such as a selector or duration.
  • fill: fills form fields, automatically detecting the field type and handling text input, dropdown selection, checkboxes, and radio buttons.
  • click: clicks an element, with the parameter target.
  • scroll: scrolls the page, with the parameter to (such as 'bottom').
  • screenshot: takes a screenshot, and fullPage etc. can be specified.

Composite mode (new version): a high-level mode that can automatically expand into multiple steps.

Validation mode: use validate: true to check steps before execution and return a validation analysis, including: errors (missing required parameters), warnings (step order issues, for example viewport is not first), suggestions (recommended improvements, for example adding waitFor to click), and step analysis (status and description for each step).

Tool call examples

Note: if no explicit screenshot step is provided, a screenshot is automatically taken at the end. The fill step automatically detects the field type and handles text input, dropdown selection, checkboxes, and radio buttons.

Form fill fields support:

  • selector (required): the CSS selector of the form field.
  • value (required): the value to set. Use "true" or "false" for checkboxes. Use the value attribute for dropdowns/radio buttons.
  • type (optional): a field type hint (text, select, checkbox, radio, textarea, password, email, number, tel, url, date, file). Automatically detected when not specified.
  • matchByText (optional): for select fields, match by visible text rather than value attribute.
  • delay (optional): the delay between keystrokes during text input (milliseconds).
  • formSelector (optional): the CSS selector of the form container (used to scope the field selector).
  • submit (optional): whether to submit the form after filling (default false).
  • submitSelector (optional): the selector of the submit button. If not specified, form.submit() is used or [type="submit"] is searched for.
  • waitForNavigation (optional): whether to wait for navigation after submission (default true).

Each field in the fields array in the example response supports the above options.

Advanced steps (available at runtime, but not exposed in the LLM schema)

type, hover, cookie, storage, evaluate, keypress, focus, blur, clear, upload, submit.

Legacy parameter support: for backward compatibility, some legacy parameters are available at runtime but are not exposed in the LLM schema, and a deprecation warning is logged when they are used.

Viewport presets

Available viewport presets include: desktop-fhd (1920x1080), desktop-hd (1280x720), desktop-4k (3840x2160), macbook-pro-16, ipad-pro (12.9-inch), ipad-pro-landscape, ipad (10.2-inch), surface-pro, iphone-14-pro-max, iphone-14-pro, iphone-se (3rd generation), pixel-7-pro, galaxy-s23-ultra.

Retries and telemetry

The tool automatically retries on transient failures and uses exponential backoff. Default retryable conditions: HTTP status codes 500, 502, 503, 504, 408, 429; network errors ETIMEDOUT, ECONNRESET, ENOTFOUND, ECONNREFUSED; DNS resolution failures. The retry policy can be customized.

The server emits structured telemetry events: tool.invoked, tool.completed, tool.failed, navigation.started, navigation.completed, navigation.failed, retry.attempt, retry.succeeded, browser.launched, browser.closed, screenshot.captured, dom.extracted. Programmable configuration of telemetry hooks.

Storage Backends

Screenshots can be automatically saved to configurable storage backends:

  • Local file system.
  • S3-compatible storage. Storage can be used within tool calls.

Use Cases

  • Webpage screenshots and DOM extraction in automated workflows.
  • Integration with Copilot/MCP-enabled environments.
  • As a standalone developer tool or long-running MCP sidecar.
  • AI-friendly scenarios requiring mobile emulation, form interaction, and structured data extraction.

Limitations

  • Requires permission to download the Chromium package on first run, as well as network connectivity to access target URLs.
  • Dynamic pages requiring complex authentication flows or user gestures are not yet automated.
  • Extremely long or infinitely scrolling pages may exceed default Chromium memory limits.
  • The S3 storage backend requires AWS SDK integration (includes a placeholder implementation).

Release and Contributing

Release automation is driven by semantic-release and GitHub Actions. Commits must follow the Conventional Commits specification (feat:, fix:, chore:) for automatic versioning. Published to npm after a successful build. Multi-platform images (linux/amd64, linux/arm64) are automatically built and published to Docker Hub and GitHub Container Registry, tagged with semantic version, major, major.minor, and latest. Required repository secrets: NPM_TOKEN, DOCKER_USERNAME, DOCKER_PASSWORD; GITHUB_TOKEN is automatically provided by GitHub Actions.

How to contribute: read CONTRIBUTING.md, open an issue describing the change, submit a PR that includes npm run build output and updated documentation/tests.

Author/Maintainer: Maintained by Saurabh Chase (@chasesaurabh). Contact via issues or discussions to coordinate the roadmap.

License: MIT License.

Related tools

Browse category