Puppeteer MCP — Cas d'usage, Installer & Démo en direct

Pourquoi l'utiliser

Fonctionnalités clés

Tiny surface — 7 tools covers 90% of browser automation needs
Chromium only — fast install, no extra browser binaries
CSS-selector based — predictable, no learning curve if you know the DOM
Note: repo is archived; prefer playwright MCP for anything new

Démo en direct

Aperçu en pratique

puppeteer.replay ▶ prêt

0/0

Installer

Choisissez votre client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Ouvrez Claude Desktop → Settings → Developer → Edit Config. Redémarrez après avoir enregistré.

~/.cursor/mcp.json · .cursor/mcp.json

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

Cursor utilise le même schéma mcpServers que Claude Desktop. La config projet l'emporte sur la globale.

VS Code → Cline → MCP Servers → Edit

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

Cliquez sur l'icône MCP Servers dans la barre latérale Cline, puis "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Même format que Claude Desktop. Redémarrez Windsurf pour appliquer.

~/.continue/config.json

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

Continue utilise un tableau d'objets serveur plutôt qu'une map.

~/.config/zed/settings.json

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

Ajoutez dans context_servers. Zed recharge à chaud à la sauvegarde.

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

Une seule ligne. Vérifiez avec claude mcp list. Supprimez avec claude mcp remove.

Cas d'usage

Usages concrets : Puppeteer

Screenshot a list of URLs for a visual audit

👤 QA, designers, content managers ⏱ ~10 min beginner

Quand l'utiliser : You have a list of pages and need to eyeball them all after a change.

Déroulement

Navigate and capture

For each URL in [list], navigate, wait for load, take a full-page screenshot named <slug>.png.✓ Copié

→ N screenshots saved
Diff against baseline (optional)

Compare each screenshot to the matching file in ./baseline/. Flag any that differ by more than 5% pixel diff.✓ Copié

→ Changed-page list
Summarize findings

Write a 1-paragraph summary: how many pages, how many changed, which likely need review.✓ Copié

→ Quick status you can paste into a PR description

Résultat : A baseline-ready screenshot set with a diff report, without setting up a visual regression pipeline.

Pièges

Dynamic content (dates, A/B banners) shows false diffs — Add puppeteer_evaluate to hide those elements via CSS before the screenshot

Combiner avec : filesystem

Fill a form repeatedly with test data

👤 QA engineers, backend devs testing input flows ⏱ ~15 min intermediate

Quand l'utiliser : You need to exercise a form with 20 variations of input to verify validation.

Prérequis

Test environment URL — Never run against production — spin up a staging instance

Déroulement

Navigate to the form

Open https://staging.app/signup. Take a screenshot to confirm.✓ Copié

→ Page loaded, form visible
Submit test cases

For each test case [list: {email, password, expected_error}], fill the fields, click submit, and capture the error message element's text.✓ Copié

→ Per-case actual vs expected
Report mismatches

Summarize: which cases passed, which failed, what the gap was. Take a screenshot of each failure.✓ Copié

→ Test report with evidence

Résultat : Validation coverage beyond what you'd write a Playwright spec for, in 10 minutes.

Pièges

Previous form state persists between runs — Call puppeteer_navigate to a fresh URL between cases, or explicitly clear fields with selector-based puppeteer_fill passing empty string

Find broken or missing images on a page

👤 Content/docs maintainers ⏱ ~10 min intermediate

Quand l'utiliser : Post-migration or after a CMS change — broken images are common and embarrassing.

Déroulement

Load the page

Open <URL>. Wait 2 seconds for lazy-loaded images.✓ Copié

→ Page loaded
Find broken images via evaluate

Run page.evaluate to return every <img> where naturalWidth === 0 — those failed to load. Include src and alt for each.✓ Copié

→ List of broken image sources
Repeat across the site

Repeat for these 20 URLs. Output a CSV of page, broken-img-src, alt-text.✓ Copié

→ Actionable CSV

Résultat : A concrete fix-list of broken images with the page they appear on.

Pièges

Lazy-loaded images haven't triggered yet — Scroll the page first with window.scrollTo(0, document.body.scrollHeight) via evaluate, then wait and check

Combiner avec : filesystem

Combinaisons

Associez-le à d'autres MCPs pour un effet X10

puppeteer + filesystem

Screenshot every page and save as image files for review

Open each URL in urls.txt, take a full-page screenshot, save to ./audit/<slug>.png.✓ Copié

puppeteer + sentry

Reproduce a Sentry-reported error by replaying the user's path

Sentry issue WEB-3a91 has breadcrumbs showing the user clicked .checkout-btn then filled #card-number. Reproduce that in Puppeteer and capture the console.✓ Copié

Outils

Ce que ce MCP expose

Outil	Entrées	Quand appeler	Coût
puppeteer_navigate	url	Open or redirect to a URL	free
puppeteer_screenshot	name, selector?, width?, height?	Capture the page or a specific element	disk space
puppeteer_click	selector	Click an element by CSS selector	free
puppeteer_fill	selector, value	Type into an input	free
puppeteer_select	selector, value	Choose an option from a <select>	free
puppeteer_hover	selector	Reveal hover-only menus or tooltips	free
puppeteer_evaluate	script	Run arbitrary JS in page context — last resort for anything selectors can't do	free

Coût et limites

Coût d'exécution

Quota d'API: Free — local execution
Tokens par appel: Screenshots aren't tokens; selectors/strings are small (~100 tokens per call)
Monétaire: Free
Astuce: Use puppeteer_evaluate to extract exactly what you need as JSON — don't screenshot then OCR

Sécurité

Permissions, secrets, portée

Stockage des identifiants : Never put real-user credentials in prompts — use dedicated QA accounts

Sortie de données : Browser goes wherever you navigate it; nothing to the MCP publisher

Repo is archived — no new features or security fixes. Consider migrating to playwright MCP for anything production-adjacent.

Dépannage

Erreurs courantes et correctifs

Error: Element not found

Element hasn't rendered yet. Add a short wait via puppeteer_evaluate('await new Promise(r => setTimeout(r, 1000))') or use a more specific selector that waits implicitly.

Chromium fails to launch on Linux/Docker

Install dependencies: apt-get install -y chromium-browser or use the Playwright MCP image which has everything pre-installed.

Screenshots are blank

Page hasn't loaded. After navigate, wait for a known element: puppeteer_evaluate("document.querySelector('.main') !== null") in a poll loop before screenshotting.

Alternatives

Puppeteer vs autres

Alternative	Quand l'utiliser	Compromis
Playwright MCP	Any serious browser automation — the strictly-better option	Slightly larger install, but better reliability via accessibility tree
Firecrawl MCP	You only need content extraction, not interaction	Hosted, costs credits, but handles anti-bot better
browser-tools MCP	You want to inspect YOUR real Chrome (with logged-in sessions, extensions)	Requires a Chrome extension; different use case entirely

Plus

Ressources

📖 Lire le README officiel sur GitHub

🐙 Voir les issues ouvertes

🔍 Parcourir les 400+ serveurs MCP et Skills