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는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "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는 맵이 아닌 서버 오브젝트 배열 사용.

~/.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와 조합해 10배 효율

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

Puppeteer