Extended Playwright MCP Server

This MCP server extends the official @playwright/mcp server by implementing 22 additional tools to facilitate web automation, direct uploads, element interactions, and advanced scraping workflows for AI agents. All standard Playwright tools remain 1:1 available and fully functional.

Custom Tools (Features)

1. download_and_convert_images

• Description: Downloads an image from a given URL, converts it to PNG format, and saves it locally.

• Parameters:

  • url (String, required): The URL of the image to download.

  • outputDir (String, optional): The target directory (defaults to a directory named downloads inside the current workspace).

2. browser_get_html

• Description: Extracts the raw HTML markup of a specific element (by CSS selector or Snapshot ID) or the entire page.

• Parameters:

  • target (String, optional): CSS selector or Snapshot ID. If omitted, the HTML of the entire page is returned.

3. browser_scroll_to

• Description: Scrolls the page or a specific element to coordinates or preset positions.

• Parameters:

  • target (String, optional): CSS selector or Snapshot ID of the element to scroll into view.

  • x (Number, optional): Horizontal scroll coordinate.

  • y (Number, optional): Vertical scroll coordinate.

  • position (Enum ["top", "bottom", "intoView"], optional): Scroll position preset.

4. browser_extract_table

• Description: Finds and extracts HTML table data (<table> or grid rows) and returns it as a structured JSON array.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the table or grid element.

5. browser_wait_for_network_idle

• Description: Blocks execution until all network requests on the page are completed (no network requests active for at least 500ms). Perfect for modern Single Page Applications (SPAs).

• Parameters:

  • timeout (Number, optional): Maximum timeout in milliseconds (defaults to 10000ms).

6. browser_get_attributes

• Description: Returns all HTML attributes of an element as a key-value object (e.g. class, style, data-* attributes).

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the target element.

7. browser_handle_download

• Description: Clicks an element, intercepts the triggered browser download event, and saves the file to the workspace.

• Parameters:

  • target (String, required): CSS selector of the download button or link.

  • filename (String, optional): Custom filename to save the file as locally.

8. browser_clear_input

• Description: Deterministically clears the text content of any input field or textarea.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the input field.

9. browser_manage_storage

• Description: Allows reading, writing, or clearing data from localStorage or sessionStorage.

• Parameters:

  • action (Enum ["get", "set", "clear"], required): The storage action to perform.

  • storageType (Enum ["local", "session"], required): The storage engine type.

  • key (String, optional): The key to access or modify (required for get and set).

  • value (String, optional): The value to write (required for set).

10. browser_toggle_checkbox

• Description: Checks or unchecks a checkbox or radio button element deterministically.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the target element.

  • checked (Boolean, required): Whether the element should be checked (true) or unchecked (false).

11. browser_mock_route

• Description: Intercepts and blocks network requests (e.g. blocking images/ads to save bandwidth/tokens) or fulfills them with mock HTTP responses.

• Parameters:

  • urlPattern (String, required): Glob or regex pattern (e.g. **/*.{png,jpg} or **/api/v1/data).

  • action (Enum ["abort", "mock"], required): Action to perform.

  • mockStatus (Number, optional): HTTP status code for mock responses.

  • mockBody (String, optional): Response body for mock responses.

12. browser_upload_file_direct

• Description: Directly uploads files to a file input element (<input type="file">) without needing to trigger or wait for a browser file chooser modal.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the file input element.

  • paths (Array of Strings, required): List of absolute/relative file paths to assign.

13. browser_take_screenshot_element

• Description: Captures a PNG/JPEG screenshot of a specific element and saves it to the workspace.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the target element.

  • filename (String, optional): Custom filename to save the screenshot.

  • type (Enum ["png", "jpeg"], optional): Output image format (defaults to png).

14. browser_get_page_info

• Description: Retrieves frame tree, URL, page title, user agent, tab count, and viewport information.

• Parameters: None.

15. browser_set_geolocation

• Description: Emulates a specific geographic location for testing region-restricted content.

• Parameters:

  • latitude (Number, required): Latitude between -90 and 90.

  • longitude (Number, required): Longitude between -180 and 180.

  • accuracy (Number, optional): Geolocation accuracy value.

16. browser_emulate_media

• Description: Emulates dark/light color scheme theme settings and media type queries (screen vs. print).

• Parameters:

  • colorScheme (Enum ["light", "dark", "no-preference"], optional): Emulated color scheme.

  • media (Enum ["screen", "print", "null"], optional): Emulated media type.

17. browser_focus_element

• Description: Directs DOM focus onto the target element.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the element to focus.

18. browser_dispatch_event

• Description: Dispatches a custom event (e.g. click, change, input) with optional custom initialization parameters on a target element.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the target element.

  • type (String, required): Event type string (e.g. 'change').

  • eventInit (Object, optional): Custom event initialization parameters.

19. browser_get_element_state

• Description: Checks current states of an element: whether it is visible, enabled, editable, or checked.

• Parameters:

  • target (String, required): CSS selector or Snapshot ID of the element.

20. browser_key_down_up

• Description: Separately fires keydown and keyup events for modifier controls or custom key holding.

• Parameters:

  • key (String, required): Name of the key (e.g., 'Shift', 'Control', 'a', 'ArrowUp').

  • action (Enum ["down", "up"], required): Press down or release key.

21. browser_get_links

• Description: Extracts and lists all internal and external link URLs from the current page.

• Parameters: None.

22. browser_mouse_move_click

• Description: Performs absolute mouse movement and click actions on coordinate pixels.

• Parameters:

  • x (Number, required): X coordinate in pixels.

  • y (Number, required): Y coordinate in pixels.

  • click (Boolean, optional): Set to true to click at the coordinates.

  • button (Enum ["left", "right", "middle"], optional): Mouse click button.

Related MCP server: MCP Macaco Playwright

Integration

You can bind this local MCP server to your preferred MCP client (such as Claude Desktop or Cursor). Since it runs locally, you execute it using node and the path to the compiled JavaScript bundle.

1. Claude Desktop (Configuration)

Add the server to your Claude Desktop configuration file (e.g. at %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": [
        "C:/Users/danev/Downloads/extend-playwright-mcp/dist/index.js",
        "--extension"
      ],
      "env": {
        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "PYefeTc_P7a5Ej8TmHCIshkWvtIPnlQ90H04ItZ66Aw"
      }
    }
  }
}

Note: Replace C:/Users/danev/Downloads/extend-playwright-mcp with your actual directory path if the project folder is moved. Ensure you use forward slashes (/) instead of backslashes (\) in the JSON paths.

2. Cursor (Configuration)

Add a new MCP server in Cursor:

• Name: playwright

• Type: command

• Command:

  node "C:/Users/danev/Downloads/extend-playwright-mcp/dist/index.js" --extension

• Environment Variables:

  • Name: PLAYWRIGHT_MCP_EXTENSION_TOKEN

  • Value: PYefeTc_P7a5Ej8TmHCIshkWvtIPnlQ90H04ItZ66Aw

Development and Compilation

If you modify the TypeScript code, compile the project again using:

# Install dependencies
npm install

# Compile the project (outputs to the dist/ folder)
npm run build