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.
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.
🌐 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
Node.js 18 or higher
npm or yarn
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 |
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.
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"
}
}
}'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-browsers1. 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
For stdio mode, logs are written to stderr and appear in Claude Code logs:
macOS: ~/Library/Logs/Claude/mcp-server-playwright.log
Linux: ~/.config/Claude/logs/mcp-server-playwright.log
For HTTP mode, logs appear in the terminal where you started the server.
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Run npm run build to ensure it compiles
Test your changes
Submit a pull request
MIT
Built with:
Playwright - Browser automation
Model Context Protocol SDK - MCP implementation
Zod - Schema validation
Express - HTTP server (for n8n mode)
Click on elements using the server-managed session
| Name | Required | Description | Default |
|---|---|---|---|
| selector | Yes | CSS selector of the element to click |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosure. It only mentions 'server-managed session' but fails to state what happens on element not found, whether it waits for interactability, or if it modifies the current page state. The description is too sparse for a browser automation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the purpose with no extraneous words. It earns its place entirely.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one param and no output schema, but the description omits important context such as session prerequisites, error behavior, or return value. While it is minimally viable, there is a clear gap in behavioral details that could confuse an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the selectors parameter is self-explanatory ('CSS selector of the element to click'). The description does not add further meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Click on elements') and the resource it operates on (via a server-managed session). This distinguishes it from sibling tools like navigate_url, get_content, and close_session, which have different verbs and purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention that this should be used for simple clicks in the current session or when to prefer run_playwright over this. Lacks any explicit or implicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close all browser sessions managed by the server and clear current session
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of disclosing behavior. It states that it closes all browser sessions and clears the current session, implying a destructive/cleanup action. However, it does not elaborate on side effects (e.g., unsaved data loss), whether it requires confirmation, or the impact on any ongoing Playwright operations. The description is upfront about the core action but lacks additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action verb. It communicates the essential information without redundancy (though 'clear current session' adds specificity). No fluff or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a simple tool with no parameters and no output schema, the description gives a clear indication of the tool's purpose and effect. It could be enhanced by noting the return value or any side effects on the underlying server, but for a straightforward close operation, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to explain. According to the baseline for 0-param tools, a 4 is appropriate because the description does not need to compensate for missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action with a specific verb ('Close') and resource ('all browser sessions managed by the server'). It also adds 'clear current session' to specify a related action. This distinguishes it from sibling tools like navigate_url or click_element, which perform page interactions rather than session management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or scenarios where a different tool would be more appropriate. For example, there is no mention of using it before starting a fresh session or as part of cleanup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract content from the page using the server-managed session
| Name | Required | Description | Default |
|---|---|---|---|
| selector | No | CSS selector to extract content. If omitted, extracts full page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It adds only the context of a 'server-managed session', but does not disclose the return format, error behavior, or any side effects. While 'extract' suggests read-only, it is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the main purpose, and contains no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional parameter and no output schema, the description provides the essential purpose and session context. However, it omits details about the return value or any conditions under which content extraction might fail, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the only parameter (selector) with a clear description: 'CSS selector to extract content. If omitted, extracts full page'. The description adds no additional parameter semantics, matching the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Extract content') and the target ('the page'), using the server-managed session. This distinguishes it from sibling tools like navigate_url (navigation) and click_element (interaction). It lacks an explicit comparison, but the verb and resource effectively convey the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool for retrieving page content within the session, but it does not provide explicit guidance on when to use it versus alternatives such as run_playwright or when not to use it. The usage is inferred from the name and siblings rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute custom async Playwright code using the server-managed session
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Async JavaScript code body to run with access to page, context, browser, params, console. Example: await page.click("a"); return await page.title(); | |
| timeoutMs | No | Execution timeout in milliseconds (default 15000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions the server-managed session but does not disclose potential side effects, security implications, error handling, or that arbitrary code execution can be destructive or alter session state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. There is no unnecessary information or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is powerful and complex, and while the schema covers parameters adequately, the description lacks critical context about what happens after execution, the return value, or how the code interacts with the session. It is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters documented in the schema. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes custom async Playwright code using a server-managed session. This distinguishes it from sibling tools that perform specific browser actions like navigation or clicking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it is for custom code scenarios not covered by the more specific sibling tools, but it does not explicitly state when to use this tool versus alternatives or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.1.0click_elementclose_sessionget_contentnavigate_urlrun_playwrightScored 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.
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
