docs/src/getting-started-mcp.md
The Playwright MCP server provides browser automation capabilities through the Model Context Protocol, enabling LLMs to interact with web pages using structured accessibility snapshots. It works with VS Code, Cursor, Windsurf, Claude Desktop, and any other MCP client — no vision models required.
Before you begin, make sure you have the following installed:
Add the Playwright MCP server to your client using the standard configuration:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}
Click one of the buttons below to install directly:
Or install via the VS Code CLI:
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
Or go to Cursor Settings → MCP → Add new MCP Server and use command type with npx @playwright/mcp@latest.
claude mcp add playwright npx @playwright/mcp@latest
Follow the MCP install guide and use the standard config above.
The standard configuration works with most MCP clients, including Windsurf, Cline, Goose, Kiro, Codex, Copilot CLI, and others. Consult your client's MCP documentation for where to place the config.
Once the server is connected, ask your AI assistant to interact with a web page:
Navigate to https://demo.playwright.dev/todomvc and add a few todo items.
The assistant will use Playwright MCP tools to open the browser, navigate to the page, and interact with elements — all through structured accessibility snapshots rather than screenshots.
Playwright MCP operates on the page's accessibility tree, not pixels. When a tool runs, it returns a structured snapshot showing the page elements, their roles, and text content. The LLM uses element references from these snapshots to interact with the page:
- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
- checkbox "Toggle Todo" [ref=e10]
- text: "Buy groceries"
The LLM reads this snapshot and uses ref=e5 to type into the textbox or ref=e10 to check the checkbox.
Playwright MCP provides tools for all common browser interactions:
For complex interactions that go beyond individual tool calls, use the browser_run_code tool to execute Playwright scripts directly:
Run this Playwright code to verify the todo count:
async (page) => {
const count = await page.getByTestId('todo-count').textContent();
return count;
}
Inspect network traffic and mock API responses:
Save and restore browser state including cookies and localStorage:
By default, Playwright MCP runs the browser in headed mode so you can see what's happening. To run headless:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--headless"
]
}
}
}
Choose which browser to use:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--browser=firefox"
]
}
}
}
Supported values: chrome, firefox, webkit, msedge.
Playwright MCP supports three profile modes:
ms-playwright/mcp-{channel}-profile in your platform's cache directory. Override with --user-data-dir.--isolated to enable. You can load initial state with --storage-state.--extension to enable.For advanced configuration, use a JSON config file:
npx @playwright/mcp@latest --config path/to/config.json
The config file supports browser options, context options, network rules, timeouts, and more. See the Playwright MCP repository for the full schema.
When running a headed browser on a system without a display or from IDE worker processes, start the MCP server separately with HTTP transport:
npx @playwright/mcp@latest --port 8931
Then point your MCP client to the HTTP endpoint:
{
"mcpServers": {
"playwright": {
"url": "http://localhost:8931/mcp"
}
}
}
| Action | How to do it |
|---|---|
| Install server | Add standard config to your MCP client |
| Navigate to a page | Ask: "Go to https://example.com" |
| Click an element | Ask: "Click the Submit button" |
| Fill a form | Ask: "Fill in the email field with [email protected]" |
| Take a screenshot | Ask: "Take a screenshot of the page" |
| Run Playwright code | Ask: "Run this Playwright code: ..." |
| Mock an API | Ask: "Mock the /api/users endpoint to return ..." |
| Use headed mode | Default. Pass --headless to disable |
| Choose a browser | Pass --browser=firefox in args |