How to Use Puppeteer with Claude Code for Browser Automation

Short answer: Puppeteer is the JavaScript library that controls Chrome or Firefox. Claude Code is an MCP client. To let Claude Code inspect and operate a browser, connect it to a maintained browser MCP server. Puppeteer’s documentation currently points to chrome-devtools-mcp for browser automation and debugging. Install that server and its browser dependencies according to its current documentation, add it to Claude Code at the narrowest useful scope, then verify the connection with claude mcp list or /mcp.

Direct Puppeteer code and browser MCP solve related but different problems. Use direct Puppeteer when automation belongs inside a JavaScript program or test suite. Use MCP when Claude Code needs browser tools during an interactive coding session. A Puppeteer script by itself does not expose browser actions to Claude Code.

1. How the pieces fit together

Piece	Role
Puppeteer	JavaScript API for controlling Chrome or Firefox through browser automation protocols.
MCP	Tool connection protocol that lets an AI client discover and call external capabilities.
Claude Code	The MCP client that can call browser tools while working on your code.
Browser MCP server	Process that exposes navigation, inspection, screenshots, and interaction tools to Claude Code.

Puppeteer runs headless by default and can control navigation, viewports, keyboard input, locators, screenshots, and browser shutdown. Its documentation directs users to chrome-devtools-mcp for an MCP-based automation and debugging workflow. The older @modelcontextprotocol/server-puppeteer package is deprecated and marked unsupported on npm, so do not use it as a new default.

2. Prerequisites and safe setup

Node.js and npm or another supported package manager.
Claude Code installed and authenticated.
A Chromium or Chrome installation, or the browser download provided by your chosen Puppeteer setup.
A local development page or harmless test URL for the first run.

Puppeteer normally downloads a compatible Chrome during installation. If your package manager blocks install scripts, that download may not happen. The Puppeteer documentation describes npx puppeteer browsers install as a manual installation route. puppeteer-core does not download a browser; choose it only when you intentionally provide the executable yourself.

Before enabling browser access, use a test account or local page. A browser tool may be able to read authenticated data, submit forms, change records, download files, or make purchases. Limit navigation and permissions to the task, and confirm the selected MCP server’s current security options before using it with sensitive sessions.

3. Install and verify Puppeteer directly

This standalone script demonstrates the browser capabilities that an MCP server makes available to Claude Code. Create a directory, initialize it, install Puppeteer, and save the following as capture.mjs.

npm init -y
npm install puppeteer

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
  await page.goto('http://localhost:3000', { waitUntil: 'networkidle2' });

  console.log('Title:', await page.title());
  console.log('Heading:', await page.locator('h1').first().innerText());

  await page.screenshot({ path: 'page.png', fullPage: true });
} finally {
  await browser.close();
}

Run it with node capture.mjs. This proves that Node.js, the browser binary, and your target page work independently of Claude Code. If this fails, fix the browser installation or page before debugging MCP.

Useful Puppeteer controls

await page.setViewport({ width: 1280, height: 800, deviceScaleFactor: 2 });
await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60000 });
await page.waitForSelector('[data-testid="ready"]', { timeout: 30000 });
await page.locator('button[type="submit"]').click();
await page.keyboard.type('example text');
await page.screenshot({ path: 'viewport.png' });
await page.screenshot({ path: 'full-page.png', fullPage: true });

Use an explicit readiness selector when the application has a reliable one. Network-idle waits can be unsuitable for pages with analytics, polling, or long-lived connections.

4. Connect a maintained browser MCP server to Claude Code

The exact package name, transport, and launch arguments can change. Follow the current Puppeteer documentation and the chrome-devtools-mcp setup guide for the install command and server configuration. Do not copy setup snippets for the deprecated package.

Install the maintained server and any browser dependencies using its official instructions.
Add the server to Claude Code using the server’s documented command or configuration format.
Choose the narrowest useful scope: local for one machine and project, project for shared repository configuration, or user for a user-wide setup.
Restart or reconnect Claude Code if the server instructions require it.
Run claude mcp list and open /mcp inside Claude Code to inspect the connection.
Ask Claude Code to navigate to a harmless page, read its visible heading, and take a screenshot.

Anthropic documents MCP server management and these configuration scopes in the Claude Code MCP documentation. Project-scoped servers configured through .mcp.json can require approval before use. Commit project configuration only after reviewing the command, environment variables, and permissions it grants.

A practical verification prompt

Open http://localhost:3000 in the browser tool. Report the page title and the visible h1 text. Take a screenshot without submitting forms or changing data.

Then ask for a bounded UI check:

Inspect the login page at http://localhost:3000. Check the desktop layout at 1440×900 and the mobile layout at 390×844. Do not enter credentials or click submit. Report overflow, missing labels, and console or network failures that the browser tool exposes.

5. Scope selection and team configuration

Scope	Use it when	Review point
Local	Only your machine and current project need the server.	Good default for experiments and personal work.
Project	A team needs the same server configuration in a repository.	Review `.mcp.json`; Claude Code may ask for approval before use.
User	You want the server available across projects.	Keep credentials and navigation permissions tightly controlled.

Store secrets in the environment or the server’s supported secret mechanism. Never commit API keys, browser profiles, cookies, or exported authentication state.

6. What Claude Code can do with browser tools

Open a local or remote page and inspect visible content.
Capture screenshots for visual review.
Navigate links and interact with controls when the server exposes those actions.
Check responsive layouts at several viewport sizes.
Read page structure and use locators to target elements.
Help verify a UI change while you work on the code.

Browser automation supports verification; it does not prove that every real user path, browser, device, permission, or network condition works. Keep assertions explicit and ask Claude Code to report what it could actually observe.

7. Or skip the browser setup

If you only need a clean screenshot or PDF, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners before removing more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result.

See the ScreenshotNeo API documentation for all options. The same endpoint accepts full-page capture with lazy images loaded, CSS element capture, dark mode, device presets or custom viewports, retina scale, PDF paper and margin settings, custom CSS and JavaScript, clicks, selector waits, delays, network-idle waits, blocked resources, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture, usage reporting, and an OpenAPI specification.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" \\
  -d access_key=YOUR_API_KEY \\
  --data-urlencode url=https://stripe.com \\
  -o shot.webp

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)

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(`Screenshot failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It includes 1,000 screenshots per month free without a card; paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan.

Create a free ScreenshotNeo account and start with the 1,000 free monthly screenshots.

8. Troubleshooting

Symptom	Likely cause	Fix
Browser fails to launch	Chrome was not downloaded, or install scripts were blocked.	Check the Puppeteer install output and run `npx puppeteer browsers install` as documented by Puppeteer. Confirm the selected server’s browser requirements.
`claude mcp list` does not show the server	The server was added at another scope, has an invalid configuration, or is not running.	Inspect local, project, and user configuration; validate the server’s current launch command; reconnect and check `/mcp`.
Claude Code asks for approval	The server is project-scoped.	Review the project configuration and approve only a server you trust. Use local scope while experimenting.
Page never becomes ready	The app has polling, streaming, third-party requests, or no stable readiness signal.	Use a specific selector or bounded delay instead of relying only on network idle.
Screenshot is blank	The page failed to load, content is rendered after capture, or the viewport is wrong.	Capture after a known selector appears, verify the URL and console output, and test with a larger viewport.
Interactions affect real data	The browser session contains authenticated accounts or the prompt allowed broad actions.	Use a test account, local page, explicit no-submit instructions, and narrow tool permissions.
Windows command behaves differently	The chosen server may require a platform-specific wrapper or quoting.	Follow that server’s current Windows instructions; do not reuse workarounds from the deprecated server.

9. Performance, reliability, and cost

Startup: Reusing one browser process for several pages is generally faster than launching a new process for every check, provided the server supports that lifecycle safely.
Waits: Prefer deterministic selectors and bounded timeouts. Long global delays make failures slow and hide the real readiness condition.
Page weight: Block unnecessary third-party resources only when doing so matches the behavior you want to verify; blocking them can change layout or application behavior.
Repeatability: Fix viewport, device scale, timezone, locale, test data, and target URL when comparing screenshots.
Failure handling: Capture logs and close pages and browsers in cleanup handlers. Retry only transient navigation failures, with a limit.
Cost: Direct Puppeteer cost depends on your machine or CI environment. MCP adds the runtime cost of its browser process. ScreenshotNeo bills only clean shots; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed.

10. FAQ

Does installing Puppeteer automatically connect Claude Code to a browser?

No. Puppeteer is a library. Claude Code needs an MCP server that exposes browser actions as tools.

Should I use `@modelcontextprotocol/server-puppeteer`?

No for a new setup. Its npm page marks it deprecated and unsupported. Use the maintained implementation referenced by current Puppeteer documentation and verify its own setup instructions.

Can Claude Code use my existing logged-in browser?

Only if the selected server explicitly supports that workflow and you configure it. Treat any exposed session as sensitive and prefer a test account.

Which scope should I choose first?

Use local scope for an individual experiment. Choose project scope when a team needs shared configuration and you are prepared to review approval prompts.

Is browser MCP suitable for production end-to-end testing?

It can assist with exploratory checks and UI verification. A production test suite should still define deterministic assertions, controlled data, cleanup, and the browsers and environments it must support.

Can I ask Claude Code to take screenshots without installing a browser?

Yes. ScreenshotNeo can return an image or PDF through its API and exposes screenshot tools through MCP, so Claude Code can use it without you managing a local browser process.

For current commands and server options, recheck the Puppeteer documentation, the selected MCP server’s documentation, and Claude Code’s MCP guide before publishing a shared configuration.