Installing Playwright MCP with Claude Desktop and Claude Code

Two install paths cover almost every reader of this course: Claude Desktop for chat-style sessions and Claude Code for terminal- and IDE-based work. The Playwright MCP server is the same in both cases — only the host changes. This lesson walks both setups end to end, the configuration flags worth knowing on day one, and the three failures that account for nearly every "tools not appearing" report on the issue tracker.

The MCP ecosystem ships fast. Flag names, default modes, and packaging have all changed at least once since the protocol launched. Treat the JSON snippets as a reliable starting point and check the official @playwright/mcp README if a flag stops behaving as written.

Prerequisites

• Node.js 20 or newer — node --version to check; install from nodejs.org if you're behind.
• An MCP-compatible host — Claude Desktop (download from claude.ai) or Claude Code (npm install -g @anthropic-ai/claude-code). Pick the one that matches how you actually want to work.
• A working Playwright install on the machine — npx playwright install chromium ensures the browser binary is on disk. Without it, the first AI session fails at launch.

If you've completed the Playwright with TypeScript course, the Node and browser steps are already done.

Path 1 — Claude Desktop (chat-style)

1. Install Claude Desktop from claude.ai. Sign in.

2. Open the config file. The path differs by OS:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json If the file doesn't exist yet, create it.

3. Add the Playwright MCP server entry:

   Copy

   {
     "mcpServers": {
       "playwright": {
         "command": "npx",
         "args": ["@playwright/mcp@latest"]
       }
     }
   }

4. Fully quit and relaunch Claude Desktop — not just close the window. The host reads the config at startup; a hot-reloaded window won't see the new server.

5. Verify in a fresh chat: ask "What Playwright tools do you have?" Claude lists browser_navigate, browser_click, browser_type, browser_snapshot, and others. If the tool list is empty, jump to the troubleshooting section below.

Path 2 — Claude Code (terminal/IDE)

Claude Code ships with an mcp subcommand that handles the config file for you:

npm install -g @anthropic-ai/claude-code
claude mcp add playwright npx @playwright/mcp@latest
claude mcp list

The third command should print playwright with status connected. From inside any Claude Code session you can now ask the assistant to drive the browser; tool calls show up inline like any other.

If you prefer to edit the config by hand, Claude Code uses the same mcpServers JSON shape as Claude Desktop — the per-OS path is documented in the Claude Code setup guide.

Useful flags

The Playwright MCP server takes the same kind of flags Playwright itself does. The ones worth knowing on day one:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser=chromium",
        "--headless"
      ]
    }
  }
}

• --browser=chromium|firefox|webkit — pick the engine. Chromium is the default and fastest to launch.
• --headless — no visible window. Useful once you trust the setup; leave it off the first few sessions so you can watch the AI work.
• --user-data-dir=/path/to/profile — point at a dedicated profile so cookies and localStorage persist across sessions without polluting your day-to-day browser.
• --vision — enable screenshot-based interaction (covered in chapter 2). Off by default; the snapshot mode is what you want for most flows.

You don't have to set any of these to get started. The defaults — chromium, headed, snapshot mode — are deliberately good for first-time setup.

End-to-end install flow

Troubleshooting the three usual failures

• Tools never appear in the chat. Almost always one of: a typo in the JSON (trailing comma, missing brace), a relative path that the spawned npx process can't resolve, or the host running with a stale config because you only closed the window. Validate the JSON in a linter, use absolute paths if you customised command, and fully quit and relaunch the host.
• Browser fails to launch on first call. The Chromium binary isn't on disk, or its system dependencies are missing on Linux. npx playwright install --with-deps chromium solves both.
• Permission errors on macOS. macOS gates screen access. Open System Settings → Privacy & Security → Screen Recording (and Accessibility), and grant access to Claude Desktop or your terminal. Restart the host after granting.

If the host has a developer log (Claude Desktop has one in Help → View logs), open it before running the failing command — most MCP errors are loud and obvious in the log even when the chat surface stays quiet.

⚠️ Common mistakes

• Editing the config but not restarting the host. The MCP client only reads the config at startup. Until you fully quit and relaunch, your edits are invisible — leading to the "I added it and nothing happened" report that fills issue trackers. Always restart, then verify.
• Pinning to a specific old version forever. @playwright/mcp@latest keeps you on the actively maintained release line. Pinning to a long-superseded version is fine for reproducibility but means you'll miss bug fixes and new tools. Pick a version policy deliberately rather than letting package.json drift.
• Running as a privileged user with production credentials. The MCP server inherits your shell's permissions and can drive any site the browser can reach. Use a fresh, non-admin profile and disposable test credentials. The first time you run it against a live login form is not the moment to discover this.

🎯 Practice task

Set up Playwright MCP and verify it end to end. 20 minutes.

1. Pick your host: Claude Desktop (chat) or Claude Code (terminal). If unsure, start with Claude Desktop.
2. Run node --version to confirm Node 20+. If lower, upgrade first.
3. Add the playwright entry to the MCP config (Path 1 or Path 2 above). Use the basic config — no flags yet.
4. npx playwright install chromium to ensure the browser is available.
5. Fully quit and relaunch the host. In a fresh chat, ask: "What Playwright tools do you have?" Confirm at least browser_navigate, browser_click, browser_type, and browser_snapshot appear.
6. Run the smoke prompt: "Navigate to https://playwright.dev/ and tell me the page title." You should see tool calls execute and a real browser open. Watch the calls in the chat — that visibility is your debugging surface for the rest of the course.
7. Stretch: add --browser=firefox to the args, restart, and run the same prompt against Firefox. Confirm the engine swap actually happens (you'll see a Firefox window).

Once the smoke prompt round-trips cleanly, you're set up for the next lesson — your first real AI-driven browser session, with prompts that go beyond "open this URL."