Puppeteer MCP Server Setup for Cursor IDE (2026)

How do you set up the Puppeteer MCP server in Cursor? Install the Puppeteer MCP server package, add a puppeteer block to ~/.cursor/mcp.json pointing at it, and restart Cursor. There's no API key, token, or account to authenticate — Puppeteer drives a real Chromium instance on your own machine, so the only real prerequisite is Chromium itself, which the underlying package downloads automatically the first time you install it if it isn't already present.

This is one of the few MCP servers on this site with essentially no auth section, because there's nothing to authenticate. That also means the security conversation here is different from every token-based guide on this site — see the caution below before pointing this at anything besides localhost or a staging environment.

What You Can Do With Puppeteer MCP in Cursor

Once connected, Cursor can typically:

That last point is the real differentiator from just curling a URL: a lot of modern sites render their actual content client-side, and a plain fetch only sees the empty shell. Puppeteer sees what a real visitor sees.

Prerequisites

Step 1: Install the Puppeteer MCP Server

npm install -g @modelcontextprotocol/server-puppeteer

This was one of the original reference MCP servers published alongside the filesystem and GitHub examples early in the protocol's life. Reference servers in that collection have been reorganized and occasionally archived or renamed as the ecosystem matured, so if this exact package 404s, check the modelcontextprotocol/servers repository on GitHub for wherever the Puppeteer server currently lives before assuming browser automation isn't available as an MCP server at all.

The first install downloads a bundled Chromium binary, which takes a minute or two depending on your connection — don't assume the install hung if it takes longer than a typical npm install -g.

Step 2: Configure Cursor

Open Cursor → Settings → MCP and add the Puppeteer server:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Notice what's missing compared to every other guide on this site: no env block. There's no credential to pass in.

Restart Cursor to load the configuration.

Step 3: Test the Connection

In Cursor chat, try:

Take a screenshot of https://example.com

Or, if you're testing against a local dev server:

Navigate to localhost:3000 and tell me what's in the header navigation

A real screenshot or a description that matches the actual page confirms it's working.

Step 4: Practical Workflows

Visual QA during development

Navigate to localhost:3000/checkout, take a screenshot at a mobile viewport size, and tell me if anything looks broken compared to the desktop layout

Scraping content a plain fetch can't see

Go to [a competitor's pricing page] and list the plan names and prices as they actually render on the page

Form-fill smoke testing

Fill in the signup form on localhost:3000/signup with test data, submit it, and tell me what happens — does it redirect, show an error, or just sit there?

Reproducing a reported bug

The bug in PROJ-456 says the "Add to cart" button doesn't respond on the product page. Navigate there, click it, and tell me what actually happens

Checking rendered SEO tags

Navigate to our /blog/some-post page and tell me what's actually in the page title and meta description after the page finishes rendering

Puppeteer vs. Playwright: Picking the Right Browser Automation MCP

This site's Playwright setup guide covers the other major browser automation option, and the honest answer to "which one" is that they solve overlapping problems with different trade-offs. Puppeteer is Chromium-only (or Chrome, if you point it at an existing install) and has been around longer, with a simpler, more focused API surface. Playwright supports Chromium, Firefox, and WebKit from one API and has stronger built-in handling for waiting on dynamic content and flaky selectors — which matters more the more complex the pages you're automating are.

For quick scripted tasks against a single browser engine — screenshots, simple form fills, scraping a rendered page — Puppeteer's smaller surface area is arguably easier for an AI to use correctly. For real cross-browser testing or heavily dynamic single-page apps, Playwright's extra reliability features tend to pay for their added complexity.

Troubleshooting

Chromium fails to download on install
Corporate networks and strict firewalls sometimes block the Chromium binary download. Check your npm proxy settings, or set the appropriate skip-download environment variable and point Puppeteer at an existing Chrome/Chromium install on your machine instead — check the package's own documentation for the current variable name, since this has changed across versions.

Screenshots come back blank or show a loading spinner
The page likely hadn't finished rendering when the screenshot was taken. Ask for a wait before the screenshot in your prompt ("wait for the page to fully load, then screenshot it") rather than assuming navigation and rendering complete at the same instant.

Clicks land on the wrong element
Be specific about what you're targeting — "click the blue 'Submit' button in the form" resolves more reliably than "click submit" on a page with multiple similarly-labeled elements.

Runs fine locally but times out in CI
Headless Chromium in a CI container often needs different sandboxing flags than a local run. This is a genuinely fiddly area with version-specific flag names — don't guess at the exact flag; check the package's current CI documentation rather than reusing a flag from an old Stack Overflow answer.

Slow performance on pages with heavy JavaScript
Puppeteer is running a full browser, not a lightweight HTTP client — expect each navigation to take real seconds, not milliseconds. For bulk scraping tasks, this adds up fast; it's not the right tool for scraping hundreds of pages quickly.

When Not to Use This

Because there's no auth layer, anyone with access to your Cursor config can drive a real browser through this server — including navigating to internal tools, admin panels, or anything else reachable from your machine's network. Don't point this at production admin interfaces or anything where an unintended click has real consequences (submitting a live form, deleting something through an admin UI). Keep it scoped to localhost, staging, and public pages you're comfortable an AI clicking around on.

Frequently Asked Questions

Q: Do I need an API key or account to use Puppeteer MCP?
A: No. This is a local browser-automation server with no external service behind it — there's nothing to authenticate against, unlike every token-based or OAuth-based guide elsewhere on this site.

Q: Does this work headless, or does a browser window actually pop up?
A: It runs headless (no visible window) by default in most configurations, which is what you want for background automation. Some setups support a non-headless mode for debugging, which is useful when you want to watch what the AI is actually doing rather than trust a text description of it.

Q: Can it fill out and submit real forms, or just read pages?
A: Both. Filling inputs and clicking submit buttons is a supported interaction, which is exactly why the "When Not to Use This" caution above matters — it's not a read-only tool.

Q: How is this different from just asking the AI to fetch a URL?
A: A plain fetch only sees the raw HTML response, which for a lot of modern sites is close to empty until client-side JavaScript runs and renders the actual content. Puppeteer loads a real browser, runs that JavaScript, and lets the AI see and interact with what a human visitor would actually see.

Q: Is this the same as the Playwright MCP server covered elsewhere on this site?
A: No, though they solve similar problems. Puppeteer is Chromium-focused with a simpler API; Playwright supports multiple browser engines and has more built-in reliability handling for dynamic pages. Neither is strictly better — it depends on whether you need cross-browser coverage.

Related Guides

---