mcp-playwright
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-playwright take a screenshot of the homepage at https://example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Playwright MCP Server π
π Active Fork of executeautomation/mcp-playwright
This repository is an actively maintained continuation of the original MCP Playwright server: π https://github.com/executeautomation/mcp-playwright
A Model Context Protocol server that provides browser automation capabilities using Playwright. This server enables LLMs to interact with web pages, take screenshots, generate test code, web scraps the page and execute JavaScript in a real browser environment. It is optimized for QA and E2E automation: screenshots, logs, assertions, API testing, plus full MCP HTTP/gateway support β built on the same Playwright foundations, complementary to Microsoftβs server.
Screenshot

Related MCP server: MCP Selenium Server
Documentation | API reference
Installation
You can install the package using either npm, mcp-get, or Smithery:
Using npm:
npm install -g @executeautomation/playwright-mcp-serverUsing mcp-get:
npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-serverUsing Smithery
To install Playwright MCP for Claude Desktop automatically via Smithery:
npx @smithery/cli install @executeautomation/playwright-mcp-server --client claudeInstallation in VS Code
Install the Playwright MCP server in VS Code using one of these buttons:
Alternatively, you can install the Playwright MCP server using the VS Code CLI:
# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'# For VS Code Insiders
code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@executeautomation/playwright-mcp-server"]}'After installation, the ExecuteAutomation Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
Configuration to use Playwright Server
Here's the Claude Desktop configuration to use the Playwright server:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["-y", "@executeautomation/playwright-mcp-server"]
}
}
}Streamable HTTP mode
The server supports the MCP Streamable HTTP transport so it can run behind gateways.
Start in HTTP mode (defaults to port
8000and path/mcp):npx @executeautomation/playwright-mcp-server --httpOverride the port or path:
npx @executeautomation/playwright-mcp-server --http --port 3000 --path /custom-mcp
How files are shared in HTTP mode
Generated artifacts (screenshots, PDFs, console logs, generated tests) are written into
/data/<session>/<resourceId>.<ext>on the server.Each Streamable HTTP session gets its own isolated resource namespace; links are only valid for that session and expire after the configured TTL (
--resource-ttl, default 600s). Session close or TTL expiry removes the files and their directories.Tool results return
resourceLinkspointing to download URLs:{scheme}://{host}:{port}{path}/resources/{sessionId}/{resourceId}/{filename}
(host from--host-name, scheme from--insecure, path from--path, default/mcp).In stdio mode, resource linking is disabled; tools only emit local paths.
This scope-based sharing prevents content leakage between sessions/clients while still giving HTTP clients and gateways stable download URIs.
Uploads in HTTP mode
The
playwright_upload_filetool accepts a localfilePathonly in stdio mode. In HTTP mode, you must first upload the file and passuploadResourceUri.Get the session-scoped upload URL by calling
construct_upload_url(HTTP mode only). It returns a POST multipart endpoint like{path}/uploads/{sessionId}; the session ID is embedded in the URL so no header is usually needed.Upload with
multipart/form-data(fieldfile). On success, the server responds with a session-scopedresourceUrisuch asmcp-uploads://<session>/<id>.Then call
playwright_upload_filewithuploadResourceUrito attach the uploaded file to the file input. Uploads are isolated per session/client like other resources.Agents must be able to run terminal/CLI commands (curl on Linux/macOS,
Invoke-WebRequest/iwron Windows) to upload the file before callingplaywright_upload_filein HTTP mode.Stdio mode continues to use local
filePath; HTTP mode prefers uploaded resources.
Client Configuration
Claude Desktop / VS Code (mcp.json):
{
"mcpServers": {
"playwright": {
"transport": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
}Adjust url to match your host/port/path and use https if terminated by a proxy.
CLI flags
--http: Enable Streamable HTTP transport (default: off; stdio is used when omitted).--port <number>: HTTP port (default:8000, only relevant when--httpis set).--path <path>: Base HTTP path (default:/mcp, only relevant when--httpis set).--host-name <hostname>: Hostname used in generated download URLs (default: system hostname, only relevant when--httpis set).--listen <address>: Bind address for the HTTP server (default:0.0.0.0, only relevant when--httpis set).--insecure: Usehttpscheme for download links; omit to usehttps(only relevant when--httpis set).--resource-ttl <seconds>: TTL for generated resources (default:600seconds; only affects HTTP mode).--static-user-agent: Disable the default randomized User-Agent rotation (by default, each new browser launch picks a modern UA to reduce bot detection/CAPTCHAs).
Agents / Prompts
A starter agent prompt is provided in
AGENTS.md. Create an agent in VS Code (or your client) using that prompt as a template; customize as needed.For file uploads in HTTP mode, ensure the agent has permission to run terminal/CLI commands (curl on Linux/macOS,
Invoke-WebRequest/iwron Windows) because uploads are performed via the session-specific HTTP endpoint before callingplaywright_upload_file.
Contributing
Read the CONTRIBUTING.md guidelines for required tooling (pre-commit hooks, lint/test/build steps, conventional commits, documentation updates).
The CI workflow enforces the same standards; please mirror them locally before opening a PR.
Available Tools
Tool | Purpose | Notes |
| Open a URL with optional viewport/headless/browser type | Browser launched if needed |
| Capture screenshot of page/element | HTTP mode returns resource link |
| Save page as PDF | HTTP mode returns resource link |
| Retrieve browser console logs with filters | Log file registered when saved |
| Set a file into an | In HTTP mode, upload file via |
| Return session-scoped upload URL/instructions | Use POST multipart ( |
| Core page interactions | Browser required |
| Interact inside iframes | Provide iframe selector |
| Read visible page content | HTML tool supports cleaning options |
| Override User-Agent for browser context | |
| Navigation or close browser | |
| Execute JS in page | |
| Wait for and assert network responses | |
| HTTP API helpers | |
| Record and generate Playwright tests | Generated tests are exposed as resources in HTTP mode |
Docker Support
The Playwright MCP Server is available as a pre-built Docker image with all browsers and system dependencies included. This avoids slow first-run downloads and version drift.
Using Docker
To use Docker, pull the latest image from GitHub Container Registry:
docker pull ghcr.io/aakashh242/mcp-playwright:latestRunning with Docker directly
# Run the server (stdin/stdout communication)
docker run -i --rm ghcr.io/aakashh242/mcp-playwright:latestStreamable HTTP mode in Docker
docker run --rm -p 8000:8000 -v /data:/data \
ghcr.io/aakashh242/mcp-playwright:latest \
node dist/index.js --http --insecure --host-name localhost --listen 0.0.0.0 --path /mcpMount
/datato persist session-scoped artifacts if desired.Adjust
--host-nameto the public hostname your clients/gateways use. Use--insecureforhttp; omit it forhttpsbehind a terminating proxy.Resource download URLs will be
http://<host>:8000/mcp/resources/<session>/<resourceId>/<filename>by default.The container default is headless (
PLAYWRIGHT_HEADLESS=1) and the Playwright base image already includes browsers.
Using Docker Compose (recommended for production HTTP)
Use the provided docker-compose.yml to run streamable HTTP with sensible defaults:
docker compose up -dDefaults:
HTTP mode with
--path=/mcp,--listen=0.0.0.0,--port=8000, and a--host-nameplaceholder (replace with your public hostname).Ports:
8000:8000Volumes:
./data/app-data:/app/dataand./data/resource-data:/datafor persisted session artifacts.
Using Docker with MCP Clients
To use the Dockerized server with Claude Desktop or other MCP clients, you can configure them to use Docker:
{
"mcpServers": {
"playwright": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/aakashh242/mcp-playwright:latest"]
}
}
}Building Locally
If you need to build the Docker image locally:
The Docker build handles dependencies and the TypeScript build for you:
docker build -t mcp-playwright .Then use mcp-playwright instead of ghcr.io/aakashh242/mcp-playwright:latest in the commands above.
Testing
This project uses Jest for testing. The tests are located in the src/__tests__ directory.
Running Tests
You can run the tests using one of the following commands:
# Run tests using the custom script (with coverage)
node run-tests.cjs
# Run tests using npm scripts
npm test # Run tests without coverage
npm run test:coverage # Run tests with coverage
npm run test:custom # Run tests with custom script (same as node run-tests.cjs)The test coverage report will be generated in the coverage directory.
Running evals
The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found here.
OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/tools/codegen/index.tsContributing
When adding new tools, please be mindful of the tool name length. Some clients, like Cursor, have a 60-character limit for the combined server and tool name (server_name:tool_name).
Our server name is playwright-mcp. Please ensure your tool names are short enough to not exceed this limit.
Star History
Available Tools
32 toolsclear_codegen_sessionC
Clear a code generation session without generating a test
Inputs: sessionId (required).
end_codegen_sessionC
End a code generation session and generate the test file
Inputs: sessionId (required).
get_codegen_sessionC
Get information about a code generation session
Inputs: sessionId (required).
playwright_assert_responseB
Wait for and validate a previously initiated HTTP response wait operation.
Inputs: id (required), value.
playwright_clickC
Click an element on the page
Inputs: selector (required).
playwright_click_and_switch_tabA
Click a link and switch to the newly opened tab
Inputs: selector (required).
playwright_closeB
Close the browser and release all resources
Inputs: no named parameters.
playwright_console_logsC
Retrieve console logs from the browser with filtering options
Inputs: type, search, limit, clear.
playwright_custom_user_agentC
Set a custom User Agent for the browser
Inputs: userAgent (required).
playwright_deleteC
Perform an HTTP DELETE request
Inputs: url (required).
playwright_dragC
Drag an element to a target location
Inputs: sourceSelector (required), targetSelector (required).
playwright_evaluateC
Execute JavaScript in the browser console
Inputs: script (required).
playwright_expect_responseB
Ask Playwright to start waiting for a HTTP response. This tool initiates the wait operation but does not wait for its completion.
Inputs: id (required), url (required).
playwright_fillC
fill out an input field
Inputs: selector (required), value (required).
playwright_getC
Perform an HTTP GET request
Inputs: url (required).
playwright_get_visible_htmlC
Get the HTML content of the current page. By default, all tags are removed from the output unless removeScripts is explicitly set to false.
Inputs: selector, removeScripts, removeComments, removeStyles, +4 more.
playwright_get_visible_textB
Get the visible text content of the current page
Inputs: no named parameters.
playwright_go_backB
Navigate back in browser history
Inputs: no named parameters.
playwright_go_forwardA
Navigate forward in browser history
Inputs: no named parameters.
playwright_hoverC
Hover an element on the page
Inputs: selector (required).
playwright_iframe_clickC
Click an element in an iframe on the page
Inputs: iframeSelector (required), selector (required).
playwright_iframe_fillC
Fill an element in an iframe on the page
Inputs: iframeSelector (required), selector (required), value (required).
playwright_patchC
Perform an HTTP PATCH request
Inputs: url (required), value (required).
playwright_postC
Perform an HTTP POST request
Inputs: url (required), value (required), token, headers.
playwright_press_keyC
Press a keyboard key
Inputs: key (required), selector.
playwright_putC
Perform an HTTP PUT request
Inputs: url (required), value (required).
playwright_save_as_pdfC
Save the current page as a PDF file
Inputs: outputPath (required), filename, format, printBackground, +1 more.
playwright_screenshotC
Take a screenshot of the current page or a specific element
Inputs: name (required), selector, width, height, +4 more.
playwright_selectC
Select an element on the page with Select tag
Inputs: selector (required), value (required).
playwright_upload_fileA
Upload a file to an input[type='file'] element on the page. In HTTP mode (disabled), provide an uploadResourceUri from construct_upload_url (preferred) or a reachable filePath.
Inputs: selector (required), filePath, uploadResourceUri.
start_codegen_sessionC
Start a new code generation session to record Playwright actions
Inputs: options (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 32 tools
Most tools have distinct purposes, but there is some overlap between HTTP request tools (get, post, put, patch, delete) and navigation/action tools that could cause confusion in selection. The codegen session tools are clearly separated from browser interaction tools, but within browser actions, some tools like playwright_click and playwright_iframe_click have similar purposes with minor context differences.
All tools follow a consistent snake_case naming convention with a clear 'playwright_' prefix for browser interaction tools and descriptive verb_noun patterns. The codegen session tools use similar patterns (clear_codegen_session, start_codegen_session, etc.), and HTTP tools maintain consistency (playwright_get, playwright_post, etc.).
With 32 tools, the count feels heavy for a Playwright automation server, suggesting potential over-fragmentation of functionality. While Playwright has many capabilities, this many tools might overwhelm agents and could be consolidated (e.g., HTTP methods into fewer tools). It's borderline excessive but still manageable.
The tool set provides comprehensive coverage for Playwright automation, including navigation, interaction, HTTP requests, iframe handling, code generation sessions, and utilities like screenshots and PDFs. There are no obvious gapsβit supports full browser automation workflows from basic clicks to advanced response validation and file operations.
Maintenance
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Unofficial Browserless MCP β wraps the Browserless headless-Chromium REST API (browserless.io)
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoβ¦
MCP server for Mint β AI-powered QA that runs your app in a real browser on every PR.
Related MCP Servers
AlicenseBqualityAmaintenanceA Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.142510,908,336 npm39,745Apache 2.0- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that enables browser automation through standardized MCP clients, supporting features like navigation, element interaction, and screenshots across Chrome, Firefox, and Edge browsers.MIT
- AlicenseBqualityDmaintenanceA universal browser automation MCP server using Playwright, enabling programmatic control of Chrome with 63 tools for navigation, interaction, media control, and CDP-based diagnostics.6328 npm3MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server for browser automation using Playwright to control Chrome browsers.1037 npmMIT