Published on

Getting Playwright Working Globally with Claude Code's MCP on macOS

Authors
  • avatar
    Name
    Jai
    Description
    Jai is Chief AI Architect at NeuroGen Labs, where he leads the Deep Cognition Team in developing scalable AI agents.
    Twitter

This guide shows you exactly how to set up Playwright to run globally on your MacBook and work inside Claude Code via the MCP server. You'll avoid duplicate browser downloads and get a working automation setup.

My Requirements

  • Global install of Playwright that works across multiple projects
  • Install Chromium once and share it across all Playwright uses to save disk space
  • Connect Playwright to Claude Code as an MCP server so Claude can drive Chromium
  • Prove it works by automating a browser action inside Claude Code
  • Bonus: move screenshots taken by Claude's Playwright MCP to Desktop

Step 1 — Install Playwright Globally and Chromium Once

Run these commands in your terminal:

npm install -g @playwright/test
playwright install chromium

This gives you:

  • A global Playwright CLI (playwright) available anywhere
  • Chromium installed once in the shared browser cache (~/Library/Caches/ms-playwright), preventing duplicates

Step 2 — Add Playwright MCP to Claude Code (Global Scope)

Make Claude Code aware of Playwright:

claude mcp add playwright -s user -- npx -y @playwright/mcp@latest
  • -s user makes it available in all projects
  • npx only installs the MCP package — it doesn't redownload Chromium

Check the connection:

claude mcp list

Claude confirms:

playwright: npx -y @playwright/mcp@latest - ✓ Connected
Claude MCP connection confirmation

Step 3 — Test Inside Claude Code

Tell Claude:

Use playwright mcp to open https://apimagic.ai, tell me the page title, take a screenshot, and close the browser.

Claude will:

  • Launch Chromium
  • Navigate to the site
  • Return the title
  • Save a screenshot (in a sandboxed temp directory)

Step 4 — Find and Move the Screenshot

Ask Claude:

Tell me the exact temp file path where it's saved in the MCP environment

Claude provides:

/var/folders/.../playwright-mcp-output/2025-08-13T03-28-39.793Z/-Desktop-apimagic.png

Then:

Move the screenshot to my Desktop

Claude runs:

cp "/var/folders/.../-Desktop-apimagic.png" ~/Desktop/apimagic.png

The screenshot now appears on your Desktop:

apimagic screenshot

Step 5 — Your Working Setup

You now have:

  • One Chromium install shared everywhere
  • Playwright globally installed
  • Connection to Claude Code via MCP
  • Ability to navigate, interact, and screenshot sites from Claude
  • Screenshots that can be located and moved to your Desktop

Key Success Factors

The approach that prevents duplicate installs:

  • Global Playwright CLI + playwright install chromium before adding MCP
  • Adding MCP with -s user scope to avoid per-project duplication
  • Letting Claude handle browser automation through MCP while explicitly requesting file paths when needed

Unique Insight: MCP as the Bridge

What makes this setup powerful is how MCP (Model Context Protocol) acts as a universal bridge between Claude and external tools. Unlike traditional automation where you write scripts, MCP lets you describe what you want in natural language. Claude translates your intent into browser actions, making complex automation accessible to anyone who can explain their goals clearly.

This pattern extends beyond Playwright. MCP transforms Claude from a text assistant into a controller for any tool that implements the protocol, creating a new paradigm where automation becomes conversational.

Frequently Asked Questions

1. Why install Playwright globally instead of per-project?

Global installation prevents multiple Chromium downloads (each ~400MB) across different projects. You maintain one shared browser cache while still using project-specific test configurations.

2. What does the -s user flag do when adding MCP?

The -s user flag makes the MCP server available across all your projects, not just the current one. This matches the global Playwright installation approach.

3. Can I use other browsers besides Chromium?

Yes, you can install Firefox or WebKit using playwright install firefox or playwright install webkit. The MCP server supports all Playwright browsers.

4. How do I update the Playwright MCP server?

Run claude mcp remove playwright then add it again with the same command. The npx -y flag ensures you get the latest version.

5. What if Claude can't find the browser?

Ensure your global Playwright installation is in your PATH. Run which playwright to verify. You may need to restart your terminal or Claude Code.

6. Can I use this setup with existing Playwright tests?

Absolutely. Your existing test files and configurations remain unchanged. The global installation only affects the CLI availability, not your test execution.

7. How much disk space does this save?

Each Playwright browser is ~400MB. With multiple projects, you could save several GB by avoiding duplicate browser installations.

8. Can I run this on Windows or Linux?

Yes, the commands are similar. Windows users should use PowerShell or WSL. The MCP protocol and Playwright work identically across platforms.

9. What happens if I need different browser versions?

Playwright manages browser versions automatically. If you need specific versions, use playwright install chromium@version. The global cache handles multiple versions efficiently.

10. How do I troubleshoot MCP connection issues?

Run claude mcp status playwright to check the connection. Look for error messages and ensure npx @playwright/mcp@latest runs successfully outside Claude Code.

Discuss on Twitter