Puppeteer MCP — Сценарии использования, Установка & Живое демо

Зачем использовать

Ключевые функции

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

Живое демо

Как выглядит на практике

puppeteer.replay ▶ готово

0/0

Установка

Выберите клиент

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

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

Откройте Claude Desktop → Settings → Developer → Edit Config. Перезапустите после сохранения.

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

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

Cursor использует ту же схему mcpServers, что и Claude Desktop. Конфиг проекта приоритетнее глобального.

VS Code → Cline → MCP Servers → Edit

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

Щёлкните значок MCP Servers на боковой панели Cline, затем "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Тот же формат, что и Claude Desktop. Перезапустите Windsurf для применения.

~/.continue/config.json

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

Continue использует массив объектов серверов, а не map.

~/.config/zed/settings.json

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

Добавьте в context_servers. Zed перезагружается автоматически.

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

Однострочная команда. Проверить: claude mcp list. Удалить: claude mcp remove.

Сценарии использования

Реальные сценарии: Puppeteer

Screenshot a list of URLs for a visual audit

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

Когда использовать: You have a list of pages and need to eyeball them all after a change.

Поток

Navigate and capture

For each URL in [list], navigate, wait for load, take a full-page screenshot named <slug>.png.✓ Скопировано

→ 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.✓ Скопировано

→ Changed-page list
Summarize findings

Write a 1-paragraph summary: how many pages, how many changed, which likely need review.✓ Скопировано

→ Quick status you can paste into a PR description

Итог: A baseline-ready screenshot set with a diff report, without setting up a visual regression pipeline.

Подводные камни

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

Сочетать с: filesystem

Fill a form repeatedly with test data

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

Когда использовать: You need to exercise a form with 20 variations of input to verify validation.

Предварительные требования

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

Поток

Navigate to the form

Open https://staging.app/signup. Take a screenshot to confirm.✓ Скопировано

→ 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.✓ Скопировано

→ Per-case actual vs expected
Report mismatches

Summarize: which cases passed, which failed, what the gap was. Take a screenshot of each failure.✓ Скопировано

→ Test report with evidence

Итог: Validation coverage beyond what you'd write a Playwright spec for, in 10 minutes.

Подводные камни

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

Когда использовать: Post-migration or after a CMS change — broken images are common and embarrassing.

Поток

Load the page

Open <URL>. Wait 2 seconds for lazy-loaded images.✓ Скопировано

→ 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.✓ Скопировано

→ List of broken image sources
Repeat across the site

Repeat for these 20 URLs. Output a CSV of page, broken-img-src, alt-text.✓ Скопировано

→ Actionable CSV

Итог: A concrete fix-list of broken images with the page they appear on.

Подводные камни

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

Сочетать с: filesystem

Комбинации

Сочетайте с другими MCP — эффект 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.✓ Скопировано

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.✓ Скопировано

Инструменты

Что предоставляет этот MCP

Инструмент	Входные данные	Когда вызывать	Стоимость
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

Стоимость и лимиты

Во что обходится

Квота API: Free — local execution
Токенов на вызов: Screenshots aren't tokens; selectors/strings are small (~100 tokens per call)
Деньги: Free
Совет: Use puppeteer_evaluate to extract exactly what you need as JSON — don't screenshot then OCR

Безопасность

Права, секреты, радиус поражения

Хранение учётных данных: Never put real-user credentials in prompts — use dedicated QA accounts

Исходящий трафик: 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.

Устранение неполадок

Частые ошибки и исправления

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.

Альтернативы

Puppeteer в сравнении

Альтернатива	Когда использовать	Компромисс
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

Ещё

Ресурсы

📖 Читать официальный README на GitHub

🐙 Открытые задачи

🔍 Все 400+ MCP-серверов и Skills