Playwright MCP setup guide
Get an AI to drive a real browser in about ten minutes. No test framework, no coding.
Pick your AI app in step 2 and skip the others.
Step 1. Install Node.js
Playwright MCP runs through Node. If you already use Playwright with TypeScript, you have it.
- Go to nodejs.org and download the LTS version.
- Install it with the default options.
- Open a terminal and check the version:
v22.11.0 ← any number 20 or higher is fine
Step 2. Add Playwright MCP to your AI app
Every app needs the same one line: npx @playwright/mcp@latest. Only the place you paste it changes.
Run this in a terminal, then restart VS Code:
Open Copilot Chat, switch it to Agent mode, and click the tools icon to see the Playwright tools listed.
- Open Cursor Settings, MCP, Add new MCP Server.
- Name it playwright, choose the command type.
- Command:
npx @playwright/mcp@latest, then save.
One command in your terminal:
Start Claude Code and type /mcp. You should see playwright marked as connected.
Open the app's MCP settings file and paste this block. The word mcpServers is just the name the file uses for its list of MCPs; leave it as is.
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}In Claude Desktop the file is claude_desktop_config.json (Settings, Developer, Edit Config). Quit the app fully and reopen it after saving.
Step 3. Check it worked
Type this into your AI app:
A browser window should open on its own, load the site and close the loop with the title. The first run takes longer because it downloads a browser. If it asks permission to use a Playwright tool, say yes.
Step 4. Your first three real prompts
Useful options
Add these after @playwright/mcp@latest in your command or in the args list.
| Option | What it does |
|---|---|
| --headless | Runs without a visible window. Use once you trust it. |
| --browser=firefox | Uses Firefox or webkit instead of Chrome. |
| --isolated | Fresh browser profile every time, nothing saved between runs. |
| --storage-state=auth.json | Starts already logged in, so it skips logins and OTPs. |
| --caps=vision | Lets it use screenshots too, for canvas or chart heavy pages. |
If something goes wrong
| What you see | Fix |
|---|---|
| “npx is not recognised” | Node is not installed, or the terminal was open before you installed it. Reopen the terminal. |
| Playwright tools do not show up | Fully quit and reopen the app. In VS Code, make sure Copilot is in Agent mode. |
| Browser never opens | The first run downloads a browser. Wait a minute, or run npx playwright install chromium. |
| Stuck at the login or OTP page | Use a test account without OTP, or a saved session with --storage-state. |
| Error in the settings file | A missing comma or bracket. Paste the block exactly as shown above. |
- Use staging and a throwaway test account. Never production.
- Ask it to list every check it made, then verify two of them yourself.
- Expect a slightly different path on each run. That is normal.
- Turn anything useful into a proper .spec.ts before it goes in CI.
- The agent does the clicking. Deciding if the result is right is your job.
Commands checked against the official Playwright MCP README, October 2026. Apps update their menus often; if a menu name has moved, search the app's settings for “MCP”.