OpenScreenShot

openscreenshot

Website screenshots from your terminal, your CI, or your AI agent.

A local CLI and MCP server. It drives the Chrome already on your machine.

Local by default, with no account and no API key. OpenScreenShot Cloud is optional.

Website · CLI guide · MCP guide · Report a bug

---

Quick start

npx openscreenshot shot https://example.com --out example.png --full

That opens a headless Chrome, loads the page, saves a full-page PNG, and closes the browser.

You need: Node.js 22.12 or newer, and Google Chrome, Chromium, or Microsoft Edge. The package ships no browser of its own, so the install stays small.

Install globally to use the openscreenshot command everywhere. For CI, add it to the project instead (npm i -D openscreenshot), so each run uses the version in your lockfile.

CLI

openscreenshot shot <url> [--out <file>|-] [--full] [--width <n>] [--height <n>]

[--redact ]... [--redact-pattern ]... [--redact-rect ]... [--cloud [ ]] [--key ] [--format ] openscreenshot auth login [--cloud ] openscreenshot auth logout openscreenshot serve

Examples

# Full page

openscreenshot shot https://example.com --out page.png --full

Fixed desktop viewport

openscreenshot shot https://example.com --out desktop.png --width 1440 --height 900

Narrow viewport to check a responsive layout

openscreenshot shot https://example.com --out narrow.png --width 390 --height 844

Pipe the PNG to another tool

openscreenshot shot https://example.com --out - > shot.png

Cover the account menu, every email address, and a 200x40 area at the top left

openscreenshot shot https://example.com --out safe.png --redact "#account-menu" --redact-pattern email --redact-rect 0,0,200,40

See Redaction for how it works and what it can miss.

Local output is always PNG. A .jpg or .pdf file name does not convert it. For other formats, use --cloud with --format.

A narrow viewport changes the layout width only. The CLI keeps a desktop user agent, so it does not emulate a phone's touch input or pixel ratio.

Exit codes

Exit code 0 means the CLI saved the file. It does not prove that the page loaded correctly, so look at the image for error pages or loading spinners.

MCP server

openscreenshot with no arguments on a piped stdin starts a Model Context Protocol server over stdio, which is how an MCP client runs it. openscreenshot serve does the same and stays for existing configs. Your AI client starts it as a local process; there is no URL to enter.

Add it to your client

Clients that use an mcpServers object (Claude Desktop, Cursor, Windsurf, and others):

{

"mcpServers": { "openscreenshot": { "command": "npx", "args": ["-y", "openscreenshot"] } } }

Claude Code:

claude mcp add openscreenshot -- npx -y openscreenshot

Restart or reload the client after you save the config. The client must find npx (or pnpm, bunx) on its PATH.

Tool: capture_screenshot

{ "url": "https://example.com", "fullPage": true, "width": 1440, "height": 900 }

redact has three optional lists:

{

"url": "https://example.com", "redact": { "selectors": ["#account-menu"], "patterns": ["email", "secret"], "rects": [{ "x": 0, "y": 0, "width": 200, "height": 40 }] } }

The tool returns the PNG as MCP image content (image/png). It does not write a file. To save a named file, use the CLI.

Redaction

Redaction puts black boxes over the targets in the page, and then takes the screenshot. The unredacted pixels never get into the PNG, so they never get to your MCP client or to a hosted model.

• Selectors. The box covers the element and all of its children. If a selector matches no element, or is not valid CSS, the capture fails.
• Patterns. email finds email addresses. phone finds numbers with 9 to 15 digits. secret finds common API key and token shapes (OpenAI, Anthropic, Stripe, GitHub, AWS, Slack, Google, JWT). It also finds any run of 32 or more letters, digits, and underscores that has both a letter and a digit, such as a hash. Patterns look in text and in the values of input, textarea, and select fields.
• Rectangles. Use these for canvas, images, and cross-origin iframes, where selectors and patterns cannot look. A rectangle that is fully outside the image fails the capture.

When redaction is on, the tool pauses CSS animations, places the boxes, and takes the screenshot. Then it finds the targets again. If a target moved out of its box, the capture fails. A failed capture writes no file and returns no image.

Patterns can miss text. They do not find text split across elements, text drawn in a canvas or an image, or a format they do not know. They can also cover text that only looks like a match. Look at the image before you share it.

What it can and cannot capture

Each capture starts a fresh headless browser with an empty profile.

• It can capture any page a signed-out visitor can see: public sites, docs, status pages, staging builds, and localhost dev servers.
• It cannot see your cookies or signed-in sessions. A page behind a login shows the login screen.
• It does not click, type, wait for a selector, or set cookies. Navigation waits until the network is quiet (networkidle2), for up to 30 seconds.

For signed-in pages, annotations, or PDF export, use the OpenScreenShot browser extension for Chrome and Firefox.

OpenScreenShot Cloud (optional)

OpenScreenShot Cloud is a hosted screenshot API. It renders the page on Cloud servers, so you do not need Chrome on the machine. Local mode stays the default and needs no account.

The free plan gives 100 captures per month and needs no card. A failed capture is free. Paid plans are on the pricing page.

Sign in

openscreenshot auth login

The command prints a code, such as ABCD-EFGH, and opens https://cloud.openscreenshot.app/device in your browser. Sign in with the code that Cloud sends to your email, and approve the code. The CLI then stores an API key in ~/.openscreenshot.json. To use another Cloud base URL, add --cloud . openscreenshot auth logout removes the stored key.

Cloud from the CLI

# Full-page PNG, rendered on Cloud

openscreenshot shot https://example.com --out page.png --full --cloud

PDF of the page

openscreenshot shot https://example.com --out page.pdf --cloud --format pdf

--format accepts png, jpeg, webp, pdf, html, and markdown. --full, --width, and --height work as in local mode.

The CLI uses the first API key that it finds:

1. --key osc_live_…
2. The OPENSCREENSHOT_API_KEY environment variable
3. The key that auth login stored

The base URL is --cloud , then `OPE