ScreenshotNeo
Sign in Get a free key

BlogAI agents

Puppeteer MCP Server for Web Automation

Learn what a Puppeteer MCP server is, how to install the official Puppeteer path, automate Chrome safely, and choose between community and Playwright servers.

By the ScreenshotNeo team1 October 20268 min read

Short answer: Puppeteer is a JavaScript library for controlling Chrome or Firefox. For MCP-based browser automation, the current Puppeteer documentation points developers to chrome-devtools-mcp, a Puppeteer-based server for browser automation and debugging. The generic phrase “Puppeteer MCP server” can also refer to independent community repositories, so identify the exact package before installing it.

This guide explains the official direction, shows a local Puppeteer implementation you can run yourself, describes how to connect an MCP server to an AI client, and compares the main alternatives without treating unrelated repositories as interchangeable.

What a Puppeteer MCP server does

An MCP server exposes tools that an MCP client can call. In a browser-automation setup, those tools can open pages, inspect content, click controls, fill forms, run JavaScript, and capture screenshots. Puppeteer supplies the browser-control layer: it drives Chrome or Firefox through the Chrome DevTools Protocol (CDP) or WebDriver BiDi and runs headless by default.

The terms Puppeteer, Puppeteer MCP server, and WebMCP describe different layers:

Term Meaning Use it for
Puppeteer JavaScript browser-automation library Writing deterministic scripts and services
Puppeteer MCP server An MCP adapter that exposes browser actions as tools Letting Claude, Cursor, or another MCP client operate a browser
WebMCP An experimental page API for pages to register tools Page-provided tools discovered by compatible agents

WebMCP is not the same thing as an MCP server that gives an agent control of a browser.

Which server should you install?

The official Puppeteer documentation currently directs MCP users to chrome-devtools-mcp and describes it as Puppeteer-based. Start with that documentation and its current README because package commands, transports, and client configuration can change.

Search results also include independently maintained projects named “Puppeteer MCP Server.” One such repository documents 16 tools for navigation, screenshots, clicks, forms, dropdowns, hover, JavaScript evaluation, and mouse actions, along with Docker and remote-access options. Those are claims of that repository only; do not assume they apply to chrome-devtools-mcp or another package. Before deploying a community server, check its current source, release history, authentication, network exposure, and transport.

Install Puppeteer for a local automation script

  1. Install a current Node.js release.
  2. Create a project and install Puppeteer.
  3. Run the script below to verify that the browser launches.
mkdir puppeteer-automation
cd puppeteer-automation
npm init -y
npm install puppeteer

puppeteer downloads a compatible Chrome during installation. puppeteer-core does not download a browser; use it when your environment already manages the browser binary.

Browser download failures

Some package managers block dependency install scripts. If Puppeteer is installed but no browser is available, install the required browser explicitly:

npx puppeteer browsers install

Alternatively, allow the Puppeteer install script according to your package manager’s documented policy. In locked-down CI, pin the browser and package versions together and cache the browser directory.

Run a complete Puppeteer automation script

The following Node.js program opens a page, waits for a selector, extracts data, clicks a link, and saves a screenshot. It uses a try/finally block so the browser closes on errors.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true,
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  });

  try {
    const page = await browser.newPage();
    await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
    await page.goto('https://example.com', {
      waitUntil: 'networkidle2',
      timeout: 30_000
    });

    await page.waitForSelector('h1', { timeout: 10_000 });
    const heading = await page.$eval('h1', el => el.textContent.trim());
    console.log({ heading, url: page.url() });

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

    const link = await page.$('a');
    if (link) {
      await link.click();
      await page.waitForNavigation({ waitUntil: 'networkidle2' }).catch(() => {});
      console.log('After click:', page.url());
    }
  } finally {
    await browser.close();
  }
})();

Reliable interaction patterns

  • Prefer stable selectors such as data-testid or semantic locators over brittle CSS chains.
  • Wait for the state you need: waitForSelector, a URL condition, a response, or a short explicit delay when no observable state exists.
  • Use networkidle2 carefully. Analytics, chat, and streaming connections can prevent an idle state forever.
  • Handle optional elements with a bounded timeout rather than assuming every page has the same layout.
  • Capture diagnostic HTML, the final URL, and a screenshot when a workflow fails.

Install and connect the official MCP path

Follow the current Puppeteer MCP documentation for the package command and transport supported by your client. A typical MCP client configuration has the same shape as this example, but the command and arguments must match the server’s current README:

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

After adding the server, restart the MCP client and inspect the discovered tools. Begin with a harmless task such as opening a public page and reading its title. Keep browser-control servers local unless you have deliberately configured authentication, network boundaries, and a trusted client.

Typical MCP workflow

  1. The client starts the MCP server process.
  2. The server launches or connects to a browser.
  3. The model calls a navigation or inspection tool.
  4. The server returns structured page data, a screenshot, or an action result.
  5. The model uses returned references or page state for the next action.

Tool names and returned schemas are implementation-specific. Inspect the server’s advertised tool list instead of copying calls from a different repository.

Community Puppeteer MCP servers

Independent servers can be useful when you need a particular tool set, Docker deployment, or remote transport. Treat each repository as a separate product:

  • Verify the package or repository owner and its maintenance activity.
  • Read the exact installation and transport instructions in the current README.
  • Confirm whether the server binds only to localhost or exposes a remote endpoint.
  • Require authentication before allowing remote browser control.
  • Review how secrets, cookies, uploaded files, and page contents are handled.
  • Limit the browser account’s permissions and isolate it from internal services.

Puppeteer MCP versus Playwright MCP

Playwright MCP is a separate browser-automation server. Its official documentation describes a workflow based on structured accessibility snapshots: the model reads element references from a snapshot and uses those references for navigation and interaction.

Decision axis Questions to answer
Browser engines Which engines does the selected server support in your environment?
Interaction model Does it use accessibility snapshots, locators, CSS selectors, or another representation?
Tools Are screenshots, downloads, dialogs, JavaScript evaluation, and network controls included?
Sessions Can cookies and authenticated state persist between calls?
Deployment Is it local only, or does it support a secured remote transport?
Client setup Does your MCP client support the server’s command and transport?

The available documentation does not establish a universal feature winner. Choose based on the implementation you will actually run and the workflow your agent needs.

Or skip the browser setup

If your job is to capture clean website images or PDFs rather than let an agent perform arbitrary browser interactions, ScreenshotNeo provides a single HTTP request. Its consent handling accepts cookie banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks, 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 all options.

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,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', image);

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

Troubleshooting

Symptom Likely cause Fix
Browser executable not found Install script was blocked or puppeteer-core is being used without a browser path Run npx puppeteer browsers install, allow the install script, or provide an explicit executable path.
Navigation timeout The page is slow, blocked, or never becomes idle Raise the timeout, wait for a specific selector, and avoid relying on network idle for pages with persistent connections.
Click has no effect Element is covered, outside the viewport, disabled, or replaced after rendering Wait for visibility, scroll it into view, verify the selector, and wait for the resulting navigation or response.
Headless differs from headed mode Viewport, fonts, permissions, or timing differ Set the viewport explicitly, install required fonts, and reproduce with the same browser flags.
MCP client shows no tools Invalid command, process startup error, or incompatible transport Run the server command directly, inspect stderr, then compare the client configuration with the server’s current README.
Remote server is unsafe Browser-control endpoint is exposed without strong access controls Bind locally or behind a private network, require authentication, and restrict outbound access.

Performance, reliability, and cost

Performance

  • Reuse a browser process for multiple pages when isolation requirements permit it; launching Chrome for every action adds startup work.
  • Reuse pages carefully and clear cookies or storage when workflows must be independent.
  • Block unnecessary resources only when the workflow does not depend on them.
  • Use a precise wait condition instead of an unnecessarily long fixed delay.
  • Keep screenshots at the smallest viewport and device scale that satisfies the requirement.

Reliability

  • Pin Node.js, Puppeteer, and browser versions in CI.
  • Record the final URL, title, console errors, failed requests, and a diagnostic screenshot.
  • Retry only transient failures and cap retries so a broken selector does not create a loop.
  • Use separate browser contexts for different users or credentials.

Cost

Self-hosted Puppeteer costs the compute, storage, browser maintenance, and engineering time required to run it. The research dossier contains no general benchmark or market price that can be used to predict those costs. ScreenshotNeo charges only for clean shots; failed loads, bot checks, blank pages, timeouts, and cache hits are not billed.

FAQ

Is Puppeteer itself an MCP server?

No. Puppeteer is the browser-control library. An MCP server wraps browser capabilities as tools that an MCP client can discover and call.

Is chrome-devtools-mcp the same as every Puppeteer MCP repository?

No. The official Puppeteer documentation points to chrome-devtools-mcp; community repositories with similar names may expose different tools, transports, and security controls.

Should I use Puppeteer or Playwright MCP?

Compare the specific implementations against browser support, interaction model, tools, session handling, deployment, and client compatibility. Neither source establishes a universal winner.

Can an MCP server automate authenticated pages?

Yes, when the selected implementation supports the required session or browser profile. Treat cookies and credentials as secrets and isolate the browser process.

When is ScreenshotNeo a better fit?

Use it when you need repeatable screenshots or PDFs through an API, clean output without consent banners and common widgets, predictable billing for successful captures, or MCP tools for screenshot and PDF tasks.

Keep reading