How to Install and Configure Puppeteer MCP for Browser Screenshots

Use Chrome DevTools MCP for the current Puppeteer-supported workflow. Install Node.js LTS, npm, and Chrome stable or newer, then configure your MCP client to launch chrome-devtools-mcp with npx. Open a page with the server’s navigation tool and call take_screenshot.

The phrase “Puppeteer MCP” is ambiguous. Older search results may mention @modelcontextprotocol/server-puppeteer or unrelated community servers. The current Puppeteer project README points MCP users to Chrome DevTools MCP. Server versions and flags can change, so check the installed project’s documentation before pinning a production configuration.

1. Requirements

• Node.js LTS
• npm
• Chrome stable or newer
• An MCP client that supports server configuration

The MCP server can launch Chrome itself. You can also connect it to an existing Chrome process started with remote debugging.

2. Install and add the MCP server

Most MCP clients accept a JSON server definition. Add this entry to the client-specific configuration file, then restart or reload the client:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

npx -y downloads and runs the package without a separate global install. The @latest tag follows the newest published server. For reproducible builds, replace it with a specific version after checking the registry and testing that version with your client.

Use the current configuration location and reload procedure for your client. The upstream project publishes client-specific examples, including Codex CLI setup.

3. Launch Chrome headless and isolated

For automated screenshots, a headless browser and a temporary profile are usually the simplest defaults:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--headless=true",
        "--isolated=true"
      ]
    }
  }
}

--headless=true runs Chrome without a visible window. Puppeteer itself runs headless by default. --isolated=true uses a clean temporary user-data directory, preventing cookies, extensions, and prior browsing state from changing a capture.

If you only need basic navigation, script execution, and screenshots, try the --slim option:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--headless=true",
        "--isolated=true",
        "--slim"
      ]
    }
  }
}

Confirm supported flags with the documentation for the version you install. A flag removed or renamed in a later release will prevent the server from starting.

4. Connect to an existing Chrome session

To reuse a browser that you start yourself, launch Chrome with remote debugging enabled and point the MCP server at its debugging URL:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}

The --browser-url option connects to Chrome; it does not launch Chrome. The browser must already be listening on the same host and port. A typical local launch uses Chrome’s remote-debugging port 9222, but use the port you actually configured.

Remote debugging grants applications that can reach the endpoint substantial control over that browser. Keep sensitive pages closed and bind debugging to localhost unless you deliberately need another network arrangement.

5. Take a screenshot through MCP

1. Restart or reload the MCP client after saving the configuration.
2. Use the Chrome DevTools MCP navigation tool to open the target URL.
3. Wait for the page to finish the work required for the capture, such as navigation or client-side rendering.
4. Call take_screenshot.
5. Choose an output format and maximum dimensions when the tool exposes those parameters.

A practical instruction to an AI client is:

Navigate to https://example.com, wait for the page to load, then call take_screenshot in WebP format with a maximum width of 1600 pixels.

The exact tool schema is supplied by the MCP server to the client. Use the schema shown by your client rather than guessing parameter names. The server supports optional screenshot format and maximum width and height settings. PNG preserves lossless detail; JPEG and WebP generally produce smaller transfers.

6. Screenshot configuration choices

Choice	Use it when	Trade-off
Headless	Running CI, agents, or unattended jobs	No visible browser for debugging visual issues
Visible Chrome	Inspecting interactions manually	Requires a desktop session and is less convenient in CI
Isolated profile	You need repeatable, clean captures	Does not include an existing login or local storage
Existing Chrome	You need an authenticated session or an already-running browser	Remote debugging increases local browser-control exposure
PNG	Text and sharp edges must remain lossless	Larger files
JPEG or WebP	Reducing payload and model context size	Compression can affect fine detail
Maximum width/height	Keeping transfers and context predictable	Large pages may be scaled or clipped depending on the tool behavior

7. Browser installation versus MCP installation

Do not confuse Puppeteer’s browser download with starting the MCP server. The MCP server requirements are Node.js LTS, npm, and Chrome stable or newer. Separately, Puppeteer package installation can fail when a package manager blocks lifecycle scripts or cannot download its compatible browser.

If a Puppeteer browser download is missing, the documented manual remedy is:

npx puppeteer browsers install

You can also configure your package manager to permit Puppeteer’s install script. This fixes a browser dependency problem; it does not replace the chrome-devtools-mcp MCP configuration.

8. Reliable screenshot workflow

Wait for the page state you need

A navigation response does not guarantee that a single-page application has rendered its final content. Wait for the relevant selector, a known delay, or the site’s network activity to settle before taking the screenshot. If the MCP client exposes script execution, inspect the DOM or wait for a page-specific condition.

Use deterministic browser state

• Use an isolated profile for public pages and repeatable jobs.
• Reuse an existing profile only when authentication or local settings are required.
• Keep viewport and maximum dimensions fixed when comparing screenshots.
• Select WebP or JPEG when transfer size matters; retain PNG for pixel-sensitive review.

Control cost and context size

Maximum dimensions and compressed formats reduce the amount of data transferred to an MCP client and AI model. Capture only the page state and size needed for the task. For large pages, consider whether a full-page image is actually required or whether a viewport screenshot answers the question.

9. Troubleshooting

Symptom	Likely cause	Fix
The MCP client shows no Chrome tools	Wrong configuration file, invalid JSON, or client not reloaded	Validate the JSON, save it in the client-specific location, then restart or reload the client.
npx cannot start the server	Node.js or npm is missing, or the package cannot be resolved	Install Node.js LTS and npm, verify them with node --version and npm --version, then retry.
Chrome cannot be found	Chrome is not installed or the executable is unavailable	Install Chrome stable or newer, or configure the server with the supported custom Chrome executable option.
A Puppeteer browser download fails	Package-manager install scripts are blocked	Run npx puppeteer browsers install or allow Puppeteer’s install script. Treat this separately from MCP startup.
Existing-browser connection fails	Chrome was not started with remote debugging, or the port differs	Start Chrome with remote debugging enabled and make --browser-url use the same host and port.
The screenshot is blank or incomplete	Capture happened before client-side rendering or lazy content finished	Wait for a page-specific selector, add a suitable delay, or inspect the page with the browser tools before calling take_screenshot.
Authenticated content is missing	Isolated mode uses a fresh profile without your cookies	Connect to an existing authenticated Chrome session, or use the client/server’s supported authentication workflow.
Images are too large for the client	PNG or unrestricted dimensions create a large payload	Use WebP or JPEG and set maximum width and height.
A configuration flag is rejected	The installed version changed its supported options	Check the documentation for the installed version and remove or rename the flag.

10. Security considerations

Use isolated profiles for untrusted or unrelated pages. Do not expose a remote-debugging endpoint to a network unless you understand who can reach it. A process that can connect to the debugging port can control the browser, inspect pages, and use the browser’s logged-in state. Close sensitive tabs while debugging is enabled.

11. Or skip the browser setup

If you need a screenshot API instead of maintaining Chrome and an MCP process, ScreenshotNeo returns an image or PDF from one GET request. Its cleanup steps accept cookie and consent banners before capture and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, 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. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools.

See the ScreenshotNeo API documentation for the complete option list.

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

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

One thousand screenshots a month are free with no card. Paid plans start at $5 for 3,000 shots, and every feature is on every plan. Create a free ScreenshotNeo account.

12. FAQ

Is “Puppeteer MCP” a single official package?

No. The name appears in references to multiple projects. Current Puppeteer guidance points to Chrome DevTools MCP.

Should I use @latest in production?

Use it for easy updates. Pin a tested version when reproducibility matters, and update it deliberately.

Does --browser-url start Chrome?

No. It connects to a Chrome instance that is already running with remote debugging enabled.

Why choose an isolated profile?

It prevents old cookies, extensions, and local storage from changing a clean capture.

Which format is best for screenshots sent to an AI model?

WebP or JPEG usually reduces transfer size. Use PNG when lossless text and edge detail are more important.