Playwright Vision MCP Server
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., "@Playwright Vision MCP Server Go to example.com and take a screenshot."
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 Vision MCP Server

A powerful Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. This server enables AI assistants like Claude/Cursor/ChatGPT to interact with web pages, extract content, analyze screenshots, and execute custom browser automation scripts.
This package minimizes the amount of tools to help AI Agents pick the right tool for a given prompt.
Features
π Multi-Browser Support - Chromium, Firefox, and WebKit
π Session Management - Persistent browser sessions for multi-step workflows
πΈ Screenshot Capture - Full-page and element-specific screenshots
π Content Extraction - Text content from pages or specific selectors
π±οΈ Element Interaction - Click elements and interact with pages
π Custom Scripts - Execute arbitrary Playwright code
π Dual Transport - HTTP and stdio (for Claude Code)
For detailed information about available tools, see tools.md.
Related MCP server: Playwright MCP Automation
Table of Contents
Getting Started
Prerequisites
Node.js 18 or higher
npm or yarn
Configuration
Environment Variables
Configure the server behavior using environment variables:
Variable | Description | Default | Options |
| Run browser in headless mode |
|
|
| Browser engine to use |
|
|
| Directory for saving screenshots |
| Any valid path |
| HTTP server port |
| Any valid port number |
| Authentication token for HTTP server (optional) | None | Any string |
| OpenAI API key (required for | None | String |
| Optional custom base URL for OpenAI-compatible APIs |
| String |
| Vision model for |
| Any supported OpenAI vision model |
Cursor / Claude Code / Claude Desktop Configuration
To use this server with Cursor/Claude Code/Claude Desktop, add it to your MCP settings file.
Configuration:
{
"mcpServers": {
"playwright-vision": {
"command": "npx",
"args": [
"playwright-vision-mcp"
],
"env": {
"PLAYWRIGHT_HEADLESS": "false",
"SCREENSHOT_DIR": "/Users/username/path/to/screenshots",
"BROWSER_TYPE": "chromium",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}Note: After updating the configuration, restart Claude Code/Desktop for changes to take effect.
HTTP Transport (for n8n or other HTTP clients)
Start the HTTP server:
npm install
npm start
# or with custom port
PORT=4201 npm start
# With authentication (recommended)
MCP_AUTH_TOKEN=your-secret-token npm startThe server will listen on http://localhost:4201/mcp (or your custom port).
Authentication (Optional):
You can secure the HTTP server with token-based authentication by setting the MCP_AUTH_TOKEN environment variable. If set, all requests must include the token in the Authorization header.
Example HTTP Request (with authentication):
curl -X POST http://localhost:4201/mcp \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-secret-token" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "navigate",
"arguments": {
"url": "https://example.com"
}
}
}'Development
Development Scripts
npm install
# Start HTTP server with auto-reload
npm run dev
# Start stdio server with auto-reload
npm run dev:stdio
# Build TypeScript to JavaScript
npm run build
# Install Playwright browsers
npm run install-browsersTroubleshooting
Common Issues
1. Node.js version too old
Error: Playwright requires Node.js 18 or higherSolution: Update Node.js to version 18 or higher.
2. Browser not installed
Error: Executable doesn't exist at /path/to/browserSolution: Run npm run install-browsers
3. Permission denied (Claude Code)
Error: EACCES: permission deniedSolution: Ensure the script has execute permissions and use absolute paths in configuration.
4. Port already in use (HTTP mode)
Error: listen EADDRINUSE: address already in use :::4201Solution: Change the port with PORT=4201 npm start
Debug Logging
For stdio mode, logs are written to stderr and appear in Claude Code logs:
macOS:
~/Library/Logs/Claude/mcp-server-playwright.logLinux:
~/.config/Claude/logs/mcp-server-playwright.log
For HTTP mode, logs appear in the terminal where you started the server.
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Run
npm run buildto ensure it compilesTest your changes
Submit a pull request
License
MIT
Acknowledgments
Built with:
Playwright - Browser automation
Model Context Protocol SDK - MCP implementation
Zod - Schema validation
Express - HTTP server (for n8n mode)
Available Tools
5 toolsclick_elementB
Click on elements using the server-managed session
Inputs: selector (required).
close_sessionA
Close all browser sessions managed by the server and clear current session
Inputs: no named parameters.
get_contentB
Extract content from the page using the server-managed session
Inputs: selector.
run_playwrightA
Execute custom async Playwright code using the server-managed session
Inputs: code (required), timeoutMs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 5 tools
Each tool has a distinct roleβnavigate, click, extract content, close session, and run custom code. The run_playwright tool is a flexible escape hatch but clearly marked as executing arbitrary Playwright code, so it does not create confusion with the other specific tools.
All tool names follow a consistent verb_noun pattern in snake_case: navigate_url, click_element, get_content, close_session, run_playwright. This makes the API predictable and easy to navigate.
With 5 tools, the server is well-scoped for browser automation. It covers navigation, interaction, content extraction, session management, and a custom code option without unnecessary bloat.
The surface covers core operations like navigation, clicking, and content extraction, but misses common browser actions such as typing text, waiting for elements, or taking screenshots. The run_playwright tool can fill these gaps, but that requires custom code instead of dedicated tools.
Maintenance
Related MCP Connectors
Playwright browser automation β navigate, click, fill forms, extract, screenshot β 17 agent tools.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Hosted browser for agents: open pages, search the web, extract data, read PDFs and take screenshots.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to iβ¦
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to automate web browsers through Playwright, providing capabilities for navigation, content extraction, form filling, screenshot capture, and JavaScript execution. Supports multiple browser engines with comprehensive error handling and security features.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to control browser automation through natural language prompts using Playwright, supporting visual element interaction, PDF generation, screenshots, and testing assertions.ISC
- AlicenseNot gradedqualityDmaintenanceEnables browser automation using Playwright, allowing LLMs to interact with web pages, take screenshots, generate test code, scrape web pages, and execute JavaScript in a real browser environment.MIT
- AlicenseNot gradedqualityDmaintenanceProvides browser automation capabilities for AI assistants, enabling web navigation, form filling, and data extraction through Playwright.MIT