GetScreenshot CLI and Agent Skill
One command that saves a screenshot of any public page to a file, and a skill that teaches a coding agent when to run it. For agents that have a shell and no MCP client, and for anyone who wants to keep tool definitions out of the context window.
export GETSCREENSHOT_API_KEY=YOUR_API_KEY
npx -y getscreenshot-mcp capture https://example.com -o shot.pngWorks with any API key on any plan. The first month of the $5 plan is free with code FREE5.
The CLI
Three commands in the getscreenshot-mcp package. Nothing to install ahead of time.
capture
Captures a page and saves the image.
# Viewport, 1280x800 PNG
npx -y getscreenshot-mcp capture https://example.com/pricing -o pricing.png
# One element
npx -y getscreenshot-mcp capture https://example.com --element "header nav" -o nav.png
# Phone
npx -y getscreenshot-mcp capture https://example.com --device iphone12 -o mobile.png
# Full page
npx -y getscreenshot-mcp capture https://example.com --full-page -o full.png
# Heavy page: stop waiting on the network, then give it 4 seconds
npx -y getscreenshot-mcp capture https://example.com/app --wait-until domcontentloaded --wait-ms 4000 -o app.png| Flag | Default | What it does |
|---|---|---|
| <url> | required | Public http or https URL. URL shorteners are rejected. |
| --full-page | off | Captures the full scrollable page. |
| --element SEL | none | Captures only the element that matches a CSS selector. The capture fails if nothing matches. |
| --device NAME | none | Device preset such as iphone12, pixel2 or ipad. Sets the viewport and, for phones, a mobile user agent. The full list is in the MCP server reference. An unknown name is rejected before any capture (exit code 2, no quota used). |
| --width N, --height N | 1280, 800 | Viewport size in CSS pixels. |
| --format png|jpeg | png | Image format. |
| --wait-until X | networkidle2 | load, domcontentloaded, networkidle0 or networkidle2. domcontentloaded is the fastest and the most reliable on heavy sites. |
| --wait-ms N | 2000 | Extra wait in milliseconds before the capture. |
| --hide SEL | none | CSS selector or selectors to hide before the capture. |
| -o FILE | Also downloads the full-resolution image to this file. Without it the command only prints the image URL. | |
| --json | Prints the result as JSON, including the public URL of the screenshot. |
Cookie banners are hidden by default, and the page is scrolled once before the capture so lazy-loaded content appears.
pdf
Saves a page as an A4 PDF.
npx -y getscreenshot-mcp pdf https://example.com/invoice/123 -o invoice.pdfusage
Shows screenshots used, the monthly limit and how many are left. The call itself uses one unit of quota.
npx -y getscreenshot-mcp usageWhat you need
-
Node.js 20.9 or newer, for
npx. -
An API key in the
GETSCREENSHOT_API_KEYenvironment variable. Any plan works. Get a key. - Outbound HTTPS. The page is rendered on GetScreenshot's servers, so the machine needs no browser.
The Agent Skill
Instructions your agent loads when a task needs a screenshot
Install with the skills CLI
npx skills add rasterwise/getscreenshot-mcp
This adds a skill named getscreenshot to your agent's skills folder.
Or as a Claude Code plugin
/plugin marketplace add rasterwise/getscreenshot-mcp
Run that inside Claude Code, then install GetScreenshot from the /plugin menu.
What the skill tells the agent
- When to take a screenshot: a request to look at a URL, or a frontend change that needs a visual check.
-
To check that
GETSCREENSHOT_API_KEYis set first, and never to print the key. - To pick the smallest capture that answers the question: one element, then the viewport, then the full page.
- To open the saved file and look at it before saying a page looks right.
- What each API error means, and that failed captures still use quota.
- The limits: no localhost, public image URLs, one page load per call.
Skill and CLI, or MCP Server?
Both use the same API key and the same quota. Pick by how your agent works.
Use the skill and CLI when
- You want no tool definitions in context. An MCP server's tool schemas usually sit in the context window for the whole session. A skill costs its name and a short description until the agent needs it.
-
The agent has a shell and no MCP client. Anything that can run
npxcan take a screenshot. - You want files on disk. The image lands in the workspace, where the agent can attach it to a pull request or compare it with an earlier one.
- The same command runs in CI. A pipeline step and the agent use one tool.
Use the MCP server when
- You want images sized for the model. The MCP server downsizes captures and slices full pages, and reports the estimated token cost. The CLI saves the capture at full resolution.
- The client has no shell. A chat client that cannot run commands can still call MCP tools.
-
You need
render_htmlorcompare_screenshots. Rendering an HTML string and pixel diffs are MCP tools. - You want nothing installed. The hosted endpoint needs a URL and a header.
Worked Example: Verify My Change
An agent restyles a pricing table and checks its own work
-
1
Capture the current state
Before touching the code, the agent captures the element it is about to change from the URL that serves it today.
npx -y getscreenshot-mcp capture https://www.example.com/pricing --element ".pricing-table" -o before.png -
2
Make the change and deploy a preview
The agent edits the component, pushes the branch and waits for the preview deployment. The API cannot load
localhost, so the change has to be on a public URL. -
3
Capture again with the same flags
Same selector, preview URL. Then once more on a phone.
npx -y getscreenshot-mcp capture https://my-branch.preview.example.com/pricing --element ".pricing-table" -o after.png npx -y getscreenshot-mcp capture https://my-branch.preview.example.com/pricing --device iphone12 -o after-mobile.png -
4
Look at the images
The agent opens
before.png,after.pngandafter-mobile.pngwith its file viewing tool. It checks the thing that was meant to change, then checks that nothing next to it wrapped, overflowed or moved. -
5
Fix or report
If something is off, the agent fixes it and captures again. If it looks right, it reports what it saw and names the files. This run used three screenshots of quota.
The same loop with MCP tools, plus a rules-file snippet, is in the visual verification use case.
Limits
-
No localhost or private networks. The capture runs on GetScreenshot's servers. Deploy to a public preview URL or use a tunnel. For a single HTML file, the MCP server's
render_htmltool takes an HTML string. -
Full-page images are tall. The CLI does not slice. For a long page, capture the sections you care about with
--element, or use the MCP server. - One page load per call. No sessions and no logged-in browsing. See GetScreenshot vs Playwright MCP.
- Screenshots are stored at public URLs for 30 days. Anyone with the URL can open the image. Do not capture pages that show secrets.
- Every call uses quota, including failed ones. A typical capture takes about 9 seconds and the API gives up at 90.
Get a Key and Run the Command
The CLI and the skill work with any API key on any plan, from $5/month for 2,500 screenshots.