·

Puppeteer MCP With Claude Code Cli And Vs Code

Puppeteer MCP With Claude Code Cli And Vs Code

Installing and Connecting Puppeteer MCP to Claude Code

Claude Code is Anthropic's official CLI for Claude. It supports MCP servers natively via a JSON configuration file at ~/.claude/settings.json. Connecting Puppeteer MCP requires adding a single mcpServers entry — no plugin installation, no IDE extension, no daemon management.

Install Claude Code if you haven't already:

npm install -g @anthropic-ai/claude-code

Open or create ~/.claude/settings.json and add the Puppeteer MCP server:

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

Claude Code will launch this server as a subprocess when a session starts. The npx -y flag ensures the package is downloaded and run without prompting, which is important for non-interactive startup.

To verify the connection, start a Claude Code session and ask:

What MCP tools do you have available?

You should see puppeteer_navigate, puppeteer_screenshot, puppeteer_click, puppeteer_type, puppeteer_evaluate, and puppeteer_select listed in the response.

For headful mode during development (so you can watch the browser as the agent operates it):

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

For CI or Docker environments where sandboxing must be disabled:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {
        "PUPPETEER_LAUNCH_ARGS": "--no-sandbox --disable-setuid-sandbox"
      }
    }
  }
}

Tips
- Keep a separate settings.json profile for local debugging (headful, localhost targets) and CI (headless, sandboxing disabled). You can swap them with a symlink or a shell alias.
- Run claude --mcp-debug to see MCP server startup logs — this will immediately surface Chromium binary issues or port conflicts.
- If Claude Code reports the puppeteer tools as unavailable, verify that npx is on your PATH within the shell environment that launches Claude Code (check which npx in the same terminal).
- Pin a specific version of the MCP server in production workflows: "args": ["-y", "@modelcontextprotocol/[email protected]"] to prevent unexpected behavior from upstream updates.

Debugging Frontend Issues: Letting the Claude Agent Navigate, Inspect, and Diagnose

With Puppeteer MCP connected, Claude Code becomes capable of opening your application in a real Chromium browser and investigating bugs the same way a developer would — but faster, more methodically, and without switching context away from your terminal.

Here is a prompt pattern for diagnosing a rendering bug:

My React app at http://localhost:3000/dashboard renders a data table with a blank "Revenue"
column in production builds but not in dev builds. Please:
1. Navigate to http://localhost:3000/dashboard
2. Screenshot the current state
3. Evaluate: document.querySelectorAll('td[data-column="revenue"]') — how many cells are there,
   and what are their textContent values?
4. Check window.__APP_CONFIG__ to see if any feature flags are set
5. Look for any console errors or warnings related to data fetching or column rendering
Report your findings with the screenshot included.

Claude will execute each step, capture the screenshot, run the puppeteer_evaluate calls, and produce a structured report. You stay in your terminal — no browser tabs, no DevTools, no context switching.

For diagnosing JavaScript errors that only occur after user interaction:

Navigate to http://localhost:3000/settings. Open the browser console (I want you to capture
errors using puppeteer_evaluate after each action). Then:
1. Click the "Change Password" button
2. Type "short" into the new password field
3. Click "Save"
4. Evaluate: window.__lastError or check for any .error or .alert elements in the DOM
5. Screenshot the result
Report whether a validation error appeared and whether any JS exceptions were thrown.

When debugging CSS layout problems, the agent can extract computed styles directly:

At http://localhost:3000/landing, the hero section's CTA button is visually hidden on some
viewports. Please:
1. Set viewport to 1440x900 and screenshot
2. Evaluate the computed display, visibility, and opacity of the element with selector
   '.hero-cta-button'
3. Set viewport to 768x1024 and screenshot again
4. Evaluate the same computed styles at this viewport
5. Set viewport to 375x812 and screenshot
6. Evaluate computed styles again
Report which viewport(s) have the button hidden and what the computed style values are.

Tips
- When you don't know the CSS selector for the element causing the bug, ask the agent to evaluate document.querySelector('[data-testid]') patterns or to return document.body.outerHTML (truncated) so it can identify the right selector before interacting.
- Chain multiple puppeteer_evaluate calls to simulate the full browser state: first check performance.getEntriesByType('resource') for failed network requests, then check DOM state, then check JS error state.
- For React apps, ask the agent to evaluate window.__REACT_DEVTOOLS_GLOBAL_HOOK__.renderers to confirm whether React is mounted and which version is running.
- Always include "report any console errors" in your debugging prompts — the agent will use puppeteer_evaluate to capture console.error output that you might otherwise miss.

Automating QA Scenarios: UI Flows, Edge Cases, and Regression Checks via Claude Code

Claude Code with Puppeteer MCP can execute full QA test suites described in natural language. For teams that maintain written acceptance criteria, this means converting those criteria directly into executed test runs without writing Playwright or Cypress scripts first.

A full checkout flow QA prompt:

Execute a full checkout QA test on http://localhost:3000. Test the following scenarios:

Scenario 1 - Happy path:
  - Add the first product on /products to the cart
  - Navigate to /cart and verify the item appears
  - Proceed to checkout, fill in valid test data, complete the order
  - Screenshot the confirmation page

Scenario 2 - Empty cart checkout:
  - Navigate directly to /checkout with an empty cart
  - Screenshot and report what the page shows (redirect? error? empty state?)

Scenario 3 - Invalid email in checkout form:
  - Begin checkout, enter "notanemail" in the email field, attempt to submit
  - Screenshot the validation state

For each scenario, report: pass/fail, any console errors, and attach the relevant screenshots.

For regression checks after a specific code change:

I just updated the SearchBar component. Please run a regression check on
http://localhost:3000/search:

1. Type "laptop" in the search bar and verify results appear within 2 seconds
   (check for result elements with selector '.search-result-item')
2. Clear the search bar and verify the results disappear
3. Type a special character string: "'; DROP TABLE products;--" and verify no error
   appears and the page remains functional
4. Type a 200-character string and verify the input doesn't overflow or break layout
   (screenshot the state)
5. Press Escape and verify any open dropdowns or suggestion panels close

Report pass/fail for each check.

Tips
- Structure QA prompts with numbered scenarios so Claude's output maps directly back to your acceptance criteria — this makes the report easy to share with the team.
- For timing-sensitive checks, ask the agent to evaluate document.readyState and performance.timing.loadEventEnd to confirm the page fully loaded before asserting on DOM content.
- Include explicit "screenshot the error state" instructions in each failure scenario — screenshots are often more useful than text descriptions when reviewing QA results.
- Use Claude Code's file output capabilities alongside Puppeteer MCP: ask the agent to write a QA results summary to a file so you can store it as a test artifact.

Exploring UI Behavior and Mapping Interaction Paths with Puppeteer MCP

Beyond scripted testing, Claude Code with Puppeteer MCP excels at exploratory UI mapping — systematically visiting pages, clicking interactive elements, and building a picture of how the UI behaves across states. This is especially useful when onboarding to a new codebase or auditing an application before a refactor.

An application audit prompt:

Please explore http://localhost:3000 and build a map of the main navigation structure.
For each top-level nav item:
1. Click it and wait for navigation
2. Screenshot the resulting page
3. Note the URL it lands on
4. Identify any sub-navigation or secondary menus visible
5. Note any JavaScript console errors on that page

After visiting all nav items, produce a structured report listing:
- Page name, URL, screenshot reference
- Any pages with console errors
- Any nav items that didn't navigate (broken links or JS-handled navigation that failed)

For interaction state mapping — useful before writing a component test suite:

On http://localhost:3000/components/button-demo, please explore all button variants:
1. Screenshot the initial state of the page
2. For each visible button, click it and note what happens (state change, modal, navigation, nothing)
3. For any buttons that open modals, screenshot the modal and note the modal's close behavior
4. Report which buttons produce no visible feedback (possible bug candidates)

This exploratory output gives you a ground-truth map of actual UI behavior — verified against a running browser — which is more reliable than documentation or code comments for discovering what the UI actually does.

Tips
- For large applications, scope exploration prompts to a single feature area per session. Open-ended "explore the whole app" prompts will run long and produce noisy output.
- Ask the agent to detect dead links by evaluating document.querySelectorAll('a[href]') and checking which hrefs return 404 via fetch — this combines Puppeteer MCP with the agent's JavaScript evaluation to produce a link health report.
- When mapping interaction paths, request that the agent note the CSS classes and data-* attributes on key interactive elements — this information is directly useful for writing targeted test selectors later.
- Use the exploration output as input for a follow-up prompt: "Based on this map, write Playwright tests covering the critical paths" — the agent can convert its own exploration findings into test scaffolding.

Next Puppeteer MCP With Opencode