OpenScreenShot MCP server

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.

Package manager	Run once	Install globally
npm	npx openscreenshot shot <url>	npm i -g openscreenshot
pnpm	pnpm dlx openscreenshot shot <url>	pnpm add -g openscreenshot
Bun	bunx openscreenshot shot <url>	bun add -g openscreenshot

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 <selector>]... [--redact-pattern <name>]... [--redact-rect <x,y,w,h>]...
                    [--cloud [<base-url>]] [--key <api-key>] [--format <format>]
openscreenshot auth login [--cloud <base-url>]
openscreenshot auth logout
openscreenshot serve

Option	Default	What it does
<url>	required	The page to capture. Use a full URL with https://.
--out <file>	screenshot.png	Where to write the PNG. Use - to write bytes to stdout.
--full	off	Capture the whole scrollable page, not only the viewport.
--width <n>	1280	Viewport width in pixels, from 200 to 3840.
--height <n>	800	Viewport height in pixels, from 200 to 2160.
--redact <selector>	none	Cover the elements that match a CSS selector. Repeat for more.
--redact-pattern <name>	none	Cover text that matches email, phone, or secret. Repeat, or use a comma list.
--redact-rect <x,y,w,h>	none	Cover a rectangle, in pixels of the output image. Repeat for more.
--cloud [<base-url>]	off	Render on OpenScreenShot Cloud. See Cloud.
--key <api-key>	none	Cloud API key (osc_live_…) for this run.
--format <format>	png	With --cloud: png, jpeg, webp, pdf, html, or markdown.

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

Code	Meaning
0	The file was written.
1	The capture failed, for example Chrome not found or a timeout.
2	Bad usage or an option out of range.

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

Input	Type	Default	Notes
url	string	—	Required. A full page URL.
fullPage	boolean	false	Capture the whole page.
width	integer	1280	200 to 3840.
height	integer	800	200 to 2160.
redact	object	—	Optional. See below.
cloud	boolean	false	Render on Cloud. See Cloud.

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

redact has three optional lists:

Field	Type	What it covers
selectors	string[]	Elements that match each CSS selector.
patterns	("email" | "phone" | "secret")[]	Matching text in the page and in form values.
rects	{ x, y, width, height }[]	Rectangles, in pixels of the output image.

{
  "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 <url>. 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 <url>, then OPENSCREENSHOT_CLOUD_URL, then https://cloud.openscreenshot.app.

--redact, --redact-pattern, and --redact-rect work with --cloud. The Cloud server draws the black boxes before it returns the image. Redaction needs PNG output. As in local mode, a selector that matches nothing fails the capture, and you get no image.

Cloud from MCP

Set cloud: true on capture_screenshot to render on Cloud:

{ "url": "https://example.com", "fullPage": true, "cloud": true }

The server needs a key from openscreenshot auth login, or OPENSCREENSHOT_API_KEY in the server's env block. redact works in both modes.

Cloud also serves a remote MCP endpoint over Streamable HTTP, for clients that accept only a remote MCP URL:

• URL: https://cloud.openscreenshot.app/mcp
• Header: Authorization: Bearer <api-key>
• Tool: capture_screenshot

Privacy in Cloud mode

With --cloud or cloud: true, the URL and the options go to OpenScreenShot Cloud, and the page renders on Cloud servers. Read the Cloud privacy policy. Local mode sends nothing to OpenScreenShot.

The Cloud API docs have every option.

Use cases

• CI/CD: capture pages on every deploy for release notes, docs, or visual review. See the CI guide.
• DevOps: snapshot dashboards and status pages into incident reports and runbooks from cron or a chat command.
• AI agents: let an agent look at the page it just built or changed.

Troubleshooting

Chrome not found. The CLI checks the standard install paths on macOS, Linux, and Windows. If your browser is somewhere else, set CHROME_PATH to the executable file:

CHROME_PATH=/usr/bin/chromium openscreenshot shot https://example.com

On Windows, Chrome installed for one user lives under %LOCALAPPDATA%, and Edge is not probed. Set CHROME_PATH for both. In an MCP client, set CHROME_PATH in the server's env block.

A script hangs on openscreenshot with no arguments. With no arguments and a piped stdin, the command starts the MCP server and waits for a client. It prints one line to stderr that says so. Run openscreenshot shot <url> for a capture.

Timeout. The page did not go quiet within 30 seconds. Pages with long-polling or streaming connections can do this.

Blank or half-loaded image. Some pages render after the network goes quiet. The CLI has no extra wait option yet.

Privacy and security

• In local mode, everything runs on your machine. The package sends no telemetry and calls no OpenScreenShot server. It calls OpenScreenShot Cloud only for auth login, --cloud, or cloud: true.
• In MCP mode, your client receives the image. If the client uses a hosted model, it may send the image to that model's provider. Use redact to cover data before the image leaves the tool.
• The headless browser runs with --no-sandbox so it works in containers and CI. Capture only URLs you trust.

Links

• Source: mcp/ in PGHQdev/OpenScreenShot
• Browser extension: Chrome Web Store · Firefox Add-ons
• Support the project: ko-fi.com/pghqdev

MIT © OpenScreenShot @PGHQdev