Playwright MCP Server

How to use

To use the Playwright MCP Server, connect your MCP client to either the HTTP endpoint or the local stdio server. The HTTP mode runs as a standalone service on a port you choose, while the stdio mode runs locally and communicates via standard input/output with your client. In both modes, you can instruct the server to launch real browsers, emulate devices, take screenshots, extract data, and run scripts within a real browser context.

Key capabilities you can leverage include controlling browser pages, capturing screenshots, generating test code, scraping page data, and evaluating JavaScript in the browser. Natural language prompts like “Test on iPhone 13,” “Switch to iPad view,” or “Rotate to landscape” map to device emulation commands, enabling you to test layouts and interactions across devices with a conversational flow.

How to install

Prerequisites: You need Node.js and npm or npx available on your system. You may also opt to use Smithery or Claude Code based installation flows if you prefer their tooling.

Install using npm globally.

npm install -g @executeautomation/playwright-mcp-server

Install using mcp-get.

npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server

Install using Smithery.

npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude

If you prefer Claude Code for setup, you can add the MCP server via Claude commands.

claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server

Additional configuration and setup options

You can run the server in standard stdio mode or as an HTTP server. The stdio mode is recommended for Claude Desktop users, while HTTP mode is suitable for VS Code, custom clients, and remote deployments.

Standard Mode configuration (stdio) shows how to expose the MCP server to your client within a JSON configuration.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}

Browser installation and environment

Automatic browser installation is supported. When you first use the server and a browser is missing, it will automatically download and install Chromium, Firefox, or WebKit, display progress in the console, and retry your request after installation.

If you prefer manual installation, you can install all browsers or specific ones using Playwright commands.

npx playwright install
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

Configuration to use Playwright Server

Two primary modes are described: standard stdio mode and HTTP mode. The following shows both configurations as explicit MCP entries.

// Standard Mode (stdio) – inline configuration example
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@executeautomation/playwright-mcp-server"]
    }
  }
}
```
```json
// HTTP Mode configuration example (server URL provided)
{
  "type": "http",
  "name": "playwright_http",
  "url": "http://localhost:8931/mcp",
  "args": []
}

Troubleshooting

If you encounter a bad request error stating no transport found for a session, ensure the HTTP transport is correctly configured and that the server logs show a sequence of connection events. Restart both server and client if needed.

Common issues include port conflicts, blocked external access, and ensuring the server binds to localhost unless you configure tunneling for remote access.

Testing

Tests and evals are supported. Use provided scripts to run tests and generate coverage reports. You can run tests locally or via a custom eval flow that loads an MCP client to execute index code.

# Run tests with coverage
node run-tests.cjs
npm run test:coverage
# Run evals (example)
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts

Contributing

When adding new tools, keep tool names concise to fit MCP naming limits. The core server name for this MCP is playwright-mcp.

interact_with_page

Interact with web pages to perform actions such as clicking elements, filling inputs, navigating, and waiting for page events.

screenshot

Capture screenshots of the current browser page for verification, debugging, or visual testing.

generate_test_code

Generate test code snippets or complete tests based on observed browser interactions and page state.

web_scrape

Extract page data, text, and attributes to build structured data from web pages.

execute_javascript

Execute arbitrary JavaScript within the active browser context to perform calculations, data extraction, or page manipulation.