Guide

How to Install Playwright MCP (Claude Code Setup)

Install Playwright MCP with Node.js and npm, connect it to Claude Code, and check your setup with simple commands and troubleshooting tips.

Testml Desk 5 min read
How to Install Playwright MCP (With Claude Code)

What Playwright MCP does

To install Playwright MCP, use Node.js and npm to run its MCP server, then add that server to Claude Code. This gives Claude a way to control a browser for tasks like checking pages and testing site flows. The MCP server and the Playwright test runner are related, but they are not the same tool.

Playwright MCP uses the Model Context Protocol (MCP) to let an AI client work with a browser. It can help Claude inspect a page, click controls, enter data, and check what appears next. This is useful for browser automation and end-to-end testing.

You do not need to run npm init playwright@latest just to connect the MCP server. That command sets up a Playwright test project. Use it if you also want test files, browser setup, and a test-runner config in your project.

The setup works on macOS, Windows, and Linux, provided Node.js and npm are available. Start with a small browser task, then add more access only when needed.

Abstract browser frame connected to a node grid for Playwright MCP browser tasks
Browser tasks linked through an MCP setup

Check the setup before you install

First, install a supported Node.js version on your computer. npm comes with Node.js, so you usually do not need a separate npm install. Open a new terminal after setup so it can find the new commands.

Check that both tools work by running these commands:

  • node --version
  • npm --version

Each command should print a version number. If either command fails, install or repair Node.js before adding the MCP server. On Windows, use PowerShell or Command Prompt. On macOS and Linux, use your usual terminal.

Install Claude Code and confirm its command works in the same terminal. You also need a project folder where Claude Code can use the server. Keep browser access limited to sites and tasks you trust.

If you plan to write Playwright tests too, move into the project folder and run npm init playwright@latest. Follow the prompts to choose JavaScript or TypeScript, add test files, and install browsers. Those steps create a test project; they are optional for MCP alone.

Prepared development workspace with circuit board, ribbon cable, and blank modular blocks
Preparing a Node.js development setup

Install the Playwright MCP server

Claude Code can start the MCP server through npx. This avoids a global install and lets npm fetch the package when Claude starts it. From a terminal, run:

claude mcp add playwright -- npx -y @playwright/mcp@latest

The command adds a server named playwright to Claude Code. The -- separates Claude Code options from the server command. The -y flag lets npx confirm the package prompt without waiting for input.

For a project-only setup, run the command from that project's folder. Claude Code can then keep the server setting with the project. If you want the server available across projects, choose the user scope supported by your Claude Code version. Check claude mcp add --help for the exact scope flags.

To create a Playwright test project as well, run npm init playwright@latest from your project folder. Pick the options that match your work. For example, TypeScript suits a typed codebase, while JavaScript keeps a small test project simple.

Playwright has options for browser choice, launch settings, and access to local or remote pages. Tune these only for a clear need. For the supported server flags, run npx @playwright/mcp@latest --help or check the package's current docs.

Layered glass panels and circuit board representing a browser MCP server connection
A browser server connection in an abstract setup

Connect it to Claude Code and test it

After adding the server, start Claude Code in the chosen project. Ask it to show the available MCP tools, or use /mcp to inspect server status. The Playwright server should appear as connected.

Try a low-risk task first. For example, ask Claude to open a public page and report its title. Then ask it to find a link or describe a visible page element. These small checks show whether Claude can start the browser and use its tools.

If you use a project-scoped setup, launch Claude Code from that project folder. If the server is missing, check the saved MCP entries with claude mcp list. Remove and add the entry again if its name or command is wrong.

For browser tests, keep the test setup separate from the MCP connection. The test runner runs your test files, while MCP lets Claude control a browser during a session. You can use both in one project without treating them as one install.

Fix common setup problems

If Claude cannot find node or npx, its process may not see the terminal's PATH. Restart the terminal and Claude Code after installing Node.js. Then rerun the version checks and add command.

If the server fails to start, check the package command and internet access. Run npx -y @playwright/mcp@latest in a terminal to see whether npm can fetch it. If your network blocks package downloads, use a permitted network or your team's package mirror.

If Claude lists the server but cannot use its tools, inspect the connection with /mcp. Check that the server name matches the one you added. Then restart Claude Code so it can start a fresh server process.

On Windows, shell parsing can affect commands with flags. Keep the -- before npx, and run the add command in a supported terminal. On any system, avoid running the server with broad access to sensitive sites or data.

  • Command not found: reinstall Node.js, then open a new terminal.
  • Server not listed: check the project folder and run claude mcp list.
  • Package fetch fails: test npm access and retry the npx command.
  • Tools do not respond: check /mcp, then restart Claude Code.

Finish with a small, safe check

For MCP alone, the key steps are installing Node.js, adding the server with Claude Code, and checking its connection. The separate npm init playwright@latest command is for setting up Playwright tests, not a required MCP install step.

Once the connection works, start with a public page and a simple read-only task. Add test files or server options when your project needs them. This keeps the first setup small and makes later faults easier to trace.

Step-by-step

  1. 01
    Check Node.js and npm

    Run <code>node --version</code> and <code>npm --version</code>. Install Node.js first if either command is missing.

  2. 02
    Add the MCP server

    Run <code>claude mcp add playwright -- npx -y @playwright/mcp@latest</code> from your chosen project folder.

  3. 03
    Check the connection

    Start Claude Code and use <code>/mcp</code> to confirm the Playwright server is connected.

  4. 04
    Try a simple browser task

    Ask Claude to open a public page and report its title. Keep the first task low risk.

Frequently asked questions

How do I install Playwright MCP for Claude Code?
Install Node.js, then run <code>claude mcp add playwright -- npx -y @playwright/mcp@latest</code>. Start Claude Code and check the server with <code>/mcp</code>.
Do I need to run npm init playwright@latest to install Playwright MCP?
No. That command creates a Playwright test project. Claude Code can run the MCP server through <code>npx</code> without that setup.
How can I check whether Playwright MCP is connected?
Use <code>/mcp</code> in Claude Code to check its server status. You can also run <code>claude mcp list</code> in your terminal to see saved servers.
Does Playwright MCP work on Windows, macOS, and Linux?
Yes. It can run on these systems when Node.js, npm, and Claude Code are set up correctly. Use a terminal that can run the Claude Code command.
Why does Claude Code fail to start the Playwright MCP server?
Check that <code>node</code> and <code>npx</code> work in the same environment as Claude Code. Then verify the server command and npm network access, and restart Claude Code.
playwright mcp setupbrowser automation toolsend to end testingnode.js project setupclaude code mcp
Share XFacebookLinkedInTelegram