Name: MCP Playwright
Package: @playwright/mcp
Provider: Microsoft

Overview

MCP Playwright is a third-party MCP server from Microsoft. It lets agents control a browser to navigate pages, interact with elements, take screenshots, and extract content.

Headless by Default

Playwright MCP runs in headless mode by default. Pass --headed via args if you need a visible browser for debugging.

Usage with ADK TypeScript

import { McpPlaywright } from "@iqai/adk";

const toolset = McpPlaywright();

const tools = await toolset.getTools();

import { McpToolset } from "@iqai/adk";

const toolset = new McpToolset({
  name: "Playwright MCP Client",
  description: "Client for browser automation",
  transport: {
    mode: "stdio",
    command: "npx",
    args: ["-y", "@playwright/mcp"],
    env: {
      PATH: process.env.PATH || "",
    },
  },
});

const tools = await toolset.getTools();

If you want to use this MCP with Claude Desktop, add this to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Environment Variables

No environment variables are required for the Playwright MCP server.

Configuration Options

All MCP servers support these configuration options:

Option	Type	Description
`env`	object	Environment variables (see table above)
`debug`	boolean	Enable debug logging
`description`	string	Custom description
`retryOptions.maxRetries`	number	Max retry attempts (default: 2)
`retryOptions.initialDelay`	number	Initial retry delay in ms (default: 200)
`samplingHandler`	SamplingHandler	Handler for MCP sampling requests

Available Tools

browser_close

No parameters

Description

Close the page

browser_resize

width:numberheight:number

Description

Resize the browser window

browser_console_messages

level:stringfilename:string

Description

Returns all console messages

browser_handle_dialog

accept:booleanpromptText:string

Description

Handle a dialog

browser_evaluate

function:stringelement:stringref:string

Description

Evaluate JavaScript expression on page or element

browser_file_upload

paths:array

Description

Upload one or multiple files

browser_fill_form

fields:array

Description

Fill multiple form fields

browser_install

No parameters

Description

Install the browser specified in the config. Call this if you get an error about the browser not being installed.

browser_press_key

key:string

Description

Press a key on the keyboard

browser_type

element:stringref:stringtext:stringsubmit:booleanslowly:boolean

Description

Type text into editable element

browser_navigate

url:string

Description

Navigate to a URL

browser_navigate_back

No parameters

Description

Go back to the previous page in the history

browser_network_requests

includeStatic:booleanfilename:string

Description

Returns all network requests since loading the page

browser_run_code

code:string

Description

Run Playwright code snippet

browser_take_screenshot

type:stringfilename:stringelement:stringref:stringfullPage:boolean

Description

Take a screenshot of the current page. You can't perform actions based on the screenshot, use browser_snapshot for actions.

browser_snapshot

filename:string

Description

Capture accessibility snapshot of the current page, this is better than screenshot

browser_click

element:stringref:stringdoubleClick:booleanbutton:stringmodifiers:array

Description

Perform click on a web page

browser_drag

startElement:stringstartRef:stringendElement:stringendRef:string

Description

Perform drag and drop between two elements

browser_hover

element:stringref:string

Description

Hover over element on page

browser_select_option

element:stringref:stringvalues:array

Description

Select an option in a dropdown

browser_tabs

action:stringindex:number

Description

List, create, close, or select a browser tab.

browser_wait_for

time:numbertext:stringtextGone:string

Description

Wait for text to appear or disappear or a specified time to pass

Complete Example

import { McpPlaywright, LlmAgent } from "@iqai/adk";

async function main() {
  // Initialize Playwright toolset
  const playwrightToolset = McpPlaywright({
    debug: true,
  });

  try {
    const tools = await playwrightToolset.getTools();

    const agent = new LlmAgent({
      name: "browser_agent",
      model: "gemini-2.5-flash",
      description: "An agent that can browse the web and extract information",
      instruction: `You have access to a browser.
        Navigate to pages, extract data, and interact with elements as needed.
        Take a screenshot after navigating to confirm the page loaded.`,
      tools,
    });

    const response = await agent.ask(
      "Go to example.com and tell me what you see on the page",
    );
    console.log(response);
  } finally {
    await playwrightToolset.close();
  }
}

main();

Use Cases

Web Scraping: Extract structured data from websites
UI Testing: Automate browser-based testing workflows
Form Automation: Fill and submit web forms programmatically
Screenshot Capture: Take screenshots of web pages for analysis
Navigation Monitoring: Track redirects and page behavior
Content Extraction: Read and parse page content and metadata

Best Practices

Cleanup: Always call toolset.close() when done to free browser resources
Rate Limiting: Add delays between requests to avoid overloading servers
Error Handling: Handle navigation errors and timeouts gracefully
Respect robots.txt: Ensure you have permission to scrape target sites
Headless Mode: Use headless mode in production for better performance

Troubleshooting

Issue	Solution
Browser not launching	Ensure Playwright browsers are installed: `npx playwright install`
Navigation timeout	Increase timeout or check network connectivity
Element not found	Verify selectors and wait for page to fully load
Connection timeout	Check if npm/npx is installed and in PATH
Permission denied	Ensure the process has appropriate system permissions

MCP Playwright

On this page