Install Puppeteer in the JavaScript project that Claude Code is helping, not as part of Claude Code itself. From that project directory, run npm i puppeteer. Puppeteer normally downloads a compatible Chrome for Testing browser, after which a small JavaScript script can launch Chrome and call page.screenshot(). If you want Claude Code to control a browser directly as a tool, that is a separate MCP configuration; installing the npm package alone does not add browser tools to Claude Code.
What you are installing
Claude Code and Puppeteer are separate pieces:
- Claude Code is Anthropic’s coding agent. Its setup documentation lists Node.js 18 or newer and gives
npm install -g @anthropic-ai/claude-codeas the standard npm installation command. - Puppeteer is a JavaScript library for controlling Chrome or Firefox. It runs headless by default and exposes browser operations such as navigation, viewport changes and screenshots.
- Your project owns the Puppeteer dependency and the script that creates the image.
Anthropic says to open Claude Code from the project directory and specifically warns: “Do NOT use sudo npm install -g as this can lead to permission issues and security risks.” Install Claude Code globally only when that is how your organization manages it; install Puppeteer locally in the project.
Prerequisites and a clean project
Check Node.js and npm
In a terminal, verify that Node.js is version 18 or newer:
node --version
npm --versionIf the project does not yet have a package manifest, create one:
#1 Best Overall
mkdir browser-shots
cd browser-shots
npm init -yStart Claude Code from this same directory after installation. Keeping the agent, package manifest and screenshot script in one project makes it clear which dependency Claude Code should edit or run.
Install Puppeteer in the project
The standard installation
npm i puppeteerThe regular puppeteer package includes Puppeteer and, in applicable releases, downloads a compatible Chrome for Testing browser (and a headless shell). The browser is stored in Puppeteer’s cache by default. Package versions and browser revisions change, so let the package choose its compatible revision unless you have a specific reason to manage it yourself.
When the browser was not downloaded
Some modern package-manager configurations block dependency install scripts. In that case npm can finish without downloading Chrome, and a later launch reports that it cannot find the expected browser. Run Puppeteer’s documented browser installer manually:
npx puppeteer browsers installYou can instead allow Puppeteer’s install script in your package-manager configuration, subject to your team’s security policy. Do not solve a permissions problem by adding sudo to npm commands.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesChoose between puppeteer and puppeteer-core
| Package | Browser behavior | Use it when | What you configure |
|---|---|---|---|
puppeteer |
Downloads a compatible browser during installation when install scripts are allowed. | You want the simplest local, self-contained screenshot project. | Usually nothing beyond launch options. |
puppeteer-core |
Does not download Chrome. | Your team manages a system browser, a remote browser or a browser supplied by another service. | An executable path, browser channel or remote connection, explicitly. |
Switch to puppeteer-core only when you have a reliable browser-management plan. Installing it and then expecting Puppeteer to find a downloaded Chrome is a common source of confusion.
Ask Claude Code to create a screenshot script
Once npm i puppeteer has completed, Claude Code can create or modify a script in the project. This minimal ES module follows the documented flow: launch, open a page, set a viewport, navigate and capture.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.setViewport({ width: 1280, height: 800 });
await page.goto('http://localhost:3000', { waitUntil: 'networkidle2' });
await page.screenshot({ path: 'screenshot.png', fullPage: true });
console.log('Saved screenshot.png');
} finally {
await browser.close();
}Save it as screenshot.mjs and run:
node screenshot.mjsUsing the .mjs extension enables import without changing the project’s module settings. Alternatively, set "type": "module" in package.json and use a .js file.
Adapt the three variables that matter
- URL: replace
http://localhost:3000with a reachable local, staging or public URL. If the site requires authentication, supply credentials or cookies through Puppeteer rather than putting secrets in source control. - Readiness:
networkidle2waits for a mostly quiet network, but applications with polling, analytics or streams may never become truly idle. In those cases, wait for a stable selector or a deliberate delay instead. - Image shape: change
width,height,deviceScaleFactorandfullPageto match the browser state you need to document.
Page.screenshot() supports the capture operation. The example is a starting point, not a guarantee that every application is ready after the same wait condition.
Run Puppeteer through Claude Code
Claude Code can inspect the project, write the script and run the command if its current permissions allow terminal execution. Give it a precise request such as: “Create a Puppeteer script that opens the local app, waits for #app-ready, captures a full-page PNG at a 1440-pixel viewport, and closes the browser in a finally block.” Review the generated URL, selectors and handling of secrets before running it.
A project dependency does not automatically give Claude Code an interactive browser tool. It only gives Claude Code code that can launch Puppeteer. For direct browser interaction—clicking through a site, inspecting a page and then taking a screenshot—configure a browser automation MCP server separately. Anthropic’s MCP documentation describes adding external servers that expose tools and data sources to Claude Code. Check the selected server’s current maintainer, installation method, configuration format and security model before enabling it.
Common installation and capture failures
“Could not find Chrome” or a missing executable
Cause: the Puppeteer install script was blocked, or the cache was removed. Fix: run npx puppeteer browsers install, then rerun the script. If you intentionally use a system or remote browser, install puppeteer-core and provide its executable or connection explicitly.
Permission errors during global installation
Cause: npm is trying to write to a protected global directory. Fix: follow your Node.js installation manager’s user-level setup and avoid sudo npm install -g. Puppeteer itself should normally be installed locally with npm i puppeteer.
The page is blank or only partly rendered
Cause: the screenshot ran before client-side rendering, fonts or images finished, or the URL is unreachable from the machine running Claude Code. Fix: verify the URL manually, wait for an application-specific selector, and use a bounded delay for animations. For lazy-loaded pages, scroll or trigger the application’s loading behavior before capture.
networkidle2 never completes
Cause: long polling, WebSockets or analytics keep requests active. Fix: use a shorter navigation condition such as domcontentloaded, then wait for a selector that means the page is ready.
The screenshot has the wrong size
Cause: viewport dimensions, device scale or full-page mode do not match the intended output. Fix: set the viewport before navigation and choose fullPage: true only when you want the entire document rather than the visible viewport.
Claude Code cannot interact with the browser
Cause: Puppeteer is installed as a library, but no MCP browser server is configured. Fix: decide whether a project script is sufficient; otherwise add and secure a compatible browser automation MCP server using its current instructions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Reliability, security and repeatable captures
- Always close the browser in
finally; otherwise failed captures can leave Chrome processes running. - Use deterministic viewport dimensions, timezone, locale and test data when comparing screenshots over time.
- Keep authentication cookies, API keys and custom headers out of committed scripts and logs.
- Use a bounded timeout and report the URL and failure reason so CI can distinguish a page error from a browser startup error.
- Pin dependency versions in lockfiles for repeatable builds, while periodically reviewing Puppeteer’s current installation guidance because browser revisions and package-manager defaults change.
- For remote or system-managed browsers, document the executable path or connection endpoint and verify that the browser version is compatible with your Puppeteer release.
Or skip the browser setup
If you only need a clean website image or PDF, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF. It accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
For a direct request, see the ScreenshotNeo API documentation:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same call in Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)And Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. Features include full-page lazy-image loading, CSS-selector element capture, dark mode, device presets, retina scale, PDF page controls, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Existing parameter names used by other screenshot APIs are accepted to ease migration.
| Plan | Included shots | Price |
|---|---|---|
| Free | 1,000/month | $0, no card |
| Starter | 3,000 | $5 |
| Growth | 15,000 | $15 |
| Pro | 60,000 | $39 |
| Scale | 250,000 | $99 |
| Business | 1,000,000 | $249 |
Every feature is included on every plan, and yearly billing gives two months free. Sign up free for 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →FAQ
Does installing Puppeteer install Claude Code?
No. They are independent installations: Claude Code is installed using Anthropic’s setup method, while Puppeteer is a dependency in the project that runs browser code.
Can I use Puppeteer without downloading Chrome?
Yes. Use puppeteer-core with a browser you manage, and configure its executable, channel or remote connection explicitly.
What API actually takes the screenshot?
Puppeteer’s Page.screenshot() method captures the page after you have established the desired browser state.
Is an MCP server required for a Puppeteer script?
No. MCP is required only when you want Claude Code to receive browser interaction tools directly; a normal project script can run without MCP.
Frequently Asked Questions
Does installing Puppeteer install Claude Code?
No. Claude Code and Puppeteer are installed separately.
Can I use Puppeteer without downloading Chrome?
Yes. Use puppeteer-core and configure a browser that you manage.
What API takes the screenshot?
Puppeteer’s Page.screenshot() method.
Is MCP required for a Puppeteer script?
No. MCP is needed only for direct browser tools inside Claude Code.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
