Skip to main content
CLI is the recommended way to use Playwriter. See CLI Usage for details.
The Playwriter MCP server lets AI assistants control your Chrome browser through the Model Context Protocol.

​
Prerequisites

1

Install the Chrome extension

Install Playwriter from the Chrome Web Store
2

Enable on a tab

Click the extension icon on any tab → icon turns green when connected

​
Basic Configuration

Add Playwriter to your MCP client settings: 
{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

​
Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows): 
{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

​
Cursor

Edit .cursor/mcp.json in your project root: 
{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

​
VS Code with Continue

Edit .continue/config.json: 
{
  "mcpServers": {
    "playwriter": {
      "command": "npx",
      "args": ["-y", "playwriter@latest"]
    }
  }
}

​
Auto-Install Script

Use the installer to automatically configure your MCP client: 
npx -y @playwriter/install-mcp playwriter@latest
This detects your MCP client (Claude Desktop, Cursor, etc.) and updates the config file automatically.

​
Using the MCP Server

1

Enable extension on a tab

Click the Playwriter extension icon on at least one Chrome tab (icon turns green)
2

MCP auto-connects

The MCP server automatically starts the relay server and connects to enabled tabs
3

Use the execute tool

Ask your AI assistant to control the browser. The MCP exposes:
  • execute - Run Playwright code snippets
  • reset - Reconnect if connection issues occur

​
Available Tools

​
execute

Run Playwright code with access to page, context, and state variables. Parameters:
  • code (string, required) - JavaScript code to execute
  • timeout (number, optional) - Timeout in milliseconds (default: 10000)
Example: 
await page.goto('https://example.com')

​
reset

Recreate the CDP connection and reset browser/page/context. Use when:
  • Connection errors occur
  • Page is closed
  • Internal Playwright errors
  • No pages available in context
This clears custom properties and the state object, keeping only page, context, state (empty), and utility functions.

​
Verifying Installation

After configuring the MCP server:
  1. Restart your MCP client (Claude Desktop, Cursor, etc.)
  2. Check that the extension icon is green on at least one tab
  3. Ask the AI to navigate to a website: 
    Navigate to example.com and tell me the page title

​
Troubleshooting

​
MCP server not responding

  1. Check the relay server logs: 
    playwriter logfile
# typically: ~/.playwriter/relay-server.log
  2. Verify the extension is enabled (green icon) on at least one tab
  3. Use the reset tool to recreate the connection

​
Extension not connecting

  1. Click the extension icon on a tab (should turn green)
  2. Reload the extension from chrome://extensions
  3. Restart Chrome if issues persist

​
Chrome shows all pages as about:blank

This is a known Chrome bug in the chrome.debugger API. Restart Chrome to fix.
If the browser switches to light mode when connecting, this is a known Playwright issue.

​
Next Steps

Configuration

Set up environment variables and remote access

Remote Access

Control Chrome on remote machines over the internet

Build docs developers (and LLMs) love

Get started for freeTalk to us