CLI and Agent Skill

The getscreenshot-mcp package also runs as a command-line tool. Coding agents that can run shell commands can use it without any MCP setup, and so can scripts and CI jobs. The same repository ships an agent skill and a Claude Code plugin. All of them call the REST API and work with any API key on any plan.

Sections in this article

CLI

Capture a page and save it to a file:

export GETSCREENSHOT_API_KEY=YOUR_API_KEY
npx -y getscreenshot-mcp capture https://example.com -o example.png

The CLI reads the API key from the GETSCREENSHOT_API_KEY environment variable. Keys are emailed after checkout at getscreenshotapi.com. npx needs Node.js 20.9 or later.

Commands

npx -y getscreenshot-mcp capture <url> [--full-page] [--element SEL] [--device NAME]
                                       [--width N] [--height N] [--format png|jpeg]
                                       [--wait-until X] [--wait-ms N] [--hide SEL]
                                       [-o FILE] [--json]
npx -y getscreenshot-mcp pdf <url> [--wait-until X] [--wait-ms N] [--hide SEL] [-o FILE] [--json]
npx -y getscreenshot-mcp usage [--json]
Command What it does
capture <url> Captures a public web page as an image and prints the image URL.
pdf <url> Saves a public web page as an A4 PDF and prints the PDF URL.
usage Shows screenshots used and left this month.

Each command makes one API request and uses one screenshot from the monthly quota. That includes usage and captures that fail.

Flags for capture

Flag Description
--full-page Capture the full scrollable page instead of the viewport.
--element SEL CSS selector. Captures only that element.
--device NAME Device preset such as iphone12 or ipad. The full list is in the MCP Server reference.
--width N Viewport width in CSS pixels. The API default is 1280.
--height N Viewport height in CSS pixels. The API default is 800.
--format png or --format jpeg Image format. The default is png.
--wait-until X When the page counts as loaded: load, domcontentloaded, networkidle0 or networkidle2.
--wait-ms N Extra wait before the capture, in milliseconds.
--hide SEL CSS selector or selectors to hide before the capture.
-o FILE Also download the image to FILE. Without it the command only prints the URL.
--json Print the result as JSON, for scripts. The JSON includes the public URL of the screenshot.

pdf accepts --wait-until, --wait-ms, --hide, -o FILE and --json. usage accepts --json. Quote the URL if it contains & or spaces.

Cookie banners are hidden by default, and the page is scrolled before the capture so lazy-loaded content appears. Screenshots are stored for 30 days at a public URL with a random file name, so do not capture pages that show secrets.

Examples

# Full page, saved to a file
npx -y getscreenshot-mcp capture https://example.com --full-page -o home.png

# One component on a phone-sized viewport
npx -y getscreenshot-mcp capture https://example.com --device iphone12 --element "#pricing" -o pricing-mobile.png

# A heavy page: do not wait for the network to go idle, and hide a chat widget
npx -y getscreenshot-mcp capture https://example.com --wait-until domcontentloaded --hide ".chat-widget" -o page.png

# JSON output for scripts
npx -y getscreenshot-mcp capture https://example.com --json

# PDF
npx -y getscreenshot-mcp pdf https://example.com -o example.pdf

# Quota check
npx -y getscreenshot-mcp usage

The capture runs on GetScreenshot’s servers. The URL has to be reachable from the public internet, so localhost and private hosts do not work. Capture a preview deployment or a tunnel URL instead.

Agent skill

Install the skill into your project:

npx skills add rasterwise/getscreenshot-mcp

This adds a skill named getscreenshot. A skill is a set of instructions a coding agent loads when a task calls for it. This one needs only a shell. It tells the agent how to capture a page with the CLI or with curl, how to pick the smallest capture that answers the question, how to verify a UI change with a before and after capture, and what to do when a capture fails.

Set GETSCREENSHOT_API_KEY in the environment the agent runs in. The skill works in sandboxes, CI runners and cloud agents that have no local browser, because the browser runs on GetScreenshot’s side.

Claude Code plugin

In Claude Code, add the repository as a plugin marketplace:

/plugin marketplace add rasterwise/getscreenshot-mcp

Then install the plugin:

/plugin install getscreenshot@rasterwise

The plugin bundles the MCP Server and the skill above. It reads the API key from the GETSCREENSHOT_API_KEY environment variable, so set that before you start Claude Code.

Snippet for AGENTS.md or CLAUDE.md

Coding agents read project instruction files such as AGENTS.md and CLAUDE.md. Paste this block into yours so the agent checks UI changes with its own eyes before it reports them as done:

## Visual verification

After any change that affects how a page looks, take a screenshot and look at it
before reporting the work as done.

- Capture the preview or deployed URL of the page you changed:
  `npx -y getscreenshot-mcp capture <url> -o /tmp/shot.png`
  Then open the image file and check it.
- The capture service cannot reach localhost. Use the preview deployment URL.
  If there is none, say so instead of guessing how the page looks.
- For a layout change, also check a phone viewport: add `--device iphone12`.
- For a single component, add `--element "<css selector>"`.
- Use `--full-page` only when the change is below the fold.
- If a capture fails, retry once with `--wait-until domcontentloaded`. Do not loop.
  Every capture uses one screenshot of the monthly quota, including failed ones.
- `GETSCREENSHOT_API_KEY` is set in the environment. Never print it or commit it.
- Never put passwords or other credentials into a capture command.

Adjust the wording to your project. If your agent uses the MCP Server instead of the CLI, replace the command with the capture_screenshot tool and mention render_html for pages that only exist locally.

CI usage

This GitHub Actions job captures a staging page on every pull request and stores the image as a build artifact:

name: Screenshot
on: pull_request

jobs:
  screenshot:
    runs-on: ubuntu-latest
    steps:
      - name: Capture the staging page
        env:
          GETSCREENSHOT_API_KEY: ${{ secrets.GETSCREENSHOT_API_KEY }}
        run: npx -y getscreenshot-mcp capture "https://staging.example.com" --full-page -o screenshot.png

      - name: Upload the screenshot
        uses: actions/upload-artifact@v4
        with:
          name: screenshot
          path: screenshot.png

Notes for CI:

  • Store the API key as a repository secret named GETSCREENSHOT_API_KEY. Do not put it in the workflow file.
  • The runner needs Node.js 20.9 or later for npx. GitHub-hosted runners include Node.js.
  • The page must be public. A site served on the runner’s own localhost cannot be captured. Deploy a preview first and pass its URL.
  • Each run uses one screenshot per capture, so decide which pages matter instead of capturing every route on every commit.

MCP Server
Quickstart for LLMs and agent builders

Related Docs