Playwright Plus Python MCP

🚀 Playwright Server MCP

A Playwright-based MCP server that provides browser automation capabilities

✨ Features

Resources

The server implements a simple note storage system:

• A custom note:// URI scheme is used to access individual notes.
• Each note resource has a name, description, and a text/plain MIME type.

Prompts

The server offers a single prompting feature:

• summarize-notes: Creates a summary of all stored notes.
  • An optional "style" parameter controls the level of detail (brief/detailed).
  • Generates a prompt that combines all current notes with style preferences.

Tools

The server implements the following Playwright-related tools:

Sessions and Navigation

• playwright_new_session: Creates a new browser session and opens a browser window.

  • An optional url parameter (string) specifies the initial URL to visit. If not provided, only the browser will be opened.

• playwright_navigate: Navigates to a specified URL.

  • Requires a url parameter (string). If the URL does not contain the http or https prefix, https:// will be automatically added.
  • If there is no active browser session, a new session will be automatically created.

Page Interaction and Content Retrieval

• playwright_screenshot: Takes a screenshot of the current page or a specific element.

  • Requires a name parameter (string), the name of the screenshot file without the extension.
  • An optional selector parameter (string), a CSS selector to specify the page element to screenshot. If not provided, the entire page will be captured.

• playwright_evaluate: Executes JavaScript code in the browser console.

  • Requires a script parameter (string), the JavaScript code to be executed in the browser.

• playwright_get_text_content: Retrieves the text content of all visible elements on the current page.

  • No parameters are required.
  • It intelligently filters duplicate content and only returns meaningful text.

• playwright_get_html_content: Retrieves the HTML content of a specified element on the page.

  • Requires a selector parameter (string), a CSS selector to locate the page element whose HTML content needs to be retrieved.

Advanced Interaction Operations

• playwright_action: Supports a rich set of element selection and interaction methods.
  • Required parameters:
    • by: The way to select an element, supporting get_by_text, get_by_placeholder, get_by_label, get_by_role, etc.
    • by_value: The value for element selection.
    • action: The type of operation, such as fill, click, dblclick, hover, check, etc.
  • Optional parameters:
    • value: The value for the operation.
    • force: Whether to force the action.
    • delay: The delay between keystrokes (in milliseconds).
    • And more specific parameters, see the code documentation.

📦 Installation

System Requirements

• Python 3.10+
• Playwright 1.44+

Quick Start

Claude Desktop Configuration

MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "playwright-server": {
    "command": "uv",
    "args": [
      "--directory",
      "C:\\Users\\xxxxx\\Documents\\project\\python\\mcp\\playwright-server",
      "run",
      "playwright-server"
    ]
  }
}

"mcpServers": {
  "playwright-server": {
    "command": "uvx",
    "args": [
      "playwright-server"
    ]
  }
}

🚀 Quick Start

Building and Publishing

Prepare the release package:

1. Synchronize dependencies and update the lock file:

uv sync

2. Build the package distribution:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You need to set your PyPI credentials via environment variables or command-line parameters:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since the MCP server runs via stdio, debugging can be challenging. For the best debugging experience, we highly recommend using MCP Inspector.

You can start the MCP Inspector via npm using the following command:

npx @modelcontextprotocol/inspector uv --directory C:\Users\xxxxx\Documents\project\python\mcp\playwright-server run playwright-server

After starting, the Inspector will display a URL that you can access in your browser to start debugging.

💻 Usage Examples

Basic Web Page Access and Screenshots

# Create a session and navigate to a specified URL
await playwright_navigate(url="example.com")

# Take a screenshot of the entire page
await playwright_screenshot(name="fullpage")

# Take a screenshot of a specific element
await playwright_screenshot(name="logo", selector=".logo")

Advanced Interaction Operations

# Click a button that matches the text
await playwright_action(by="get_by_text", by_value="登录", action="click")

# Fill in a form field
await playwright_action(by="get_by_placeholder", by_value="用户名", action="fill", value="test@example.com")

# Check if an element is visible
await playwright_action(by="get_by_test_id", by_value="submit-button", action="is_visible")