Playwright MCP Server

This server provides a comprehensive set of tools to control a web browser instance using Playwright, exposed via the Model Context Protocol (MCP). It allows AI models or other MCP clients to perform complex web browsing tasks across multiple pages/tabs.

Features

• Multi-Page Management: Open, close, switch between, and list multiple browser pages/tabs. Tools target the active page by default or a specific page via page_id.
• Robust Lifecycle: Uses FastMCP's lifespan manager for reliable setup and teardown of Playwright resources (browser, pages).
• Comprehensive Tools:
  • Page Management: Open, close, switch, and list pages
  • Navigation: Go to URLs, back/forward navigation, reload
  • Content Retrieval: Get HTML, text content, titles, URLs
  • Interaction: Click, fill, type, press keys, check/uncheck, select options, hover, drag-and-drop
  • Waiting: Wait for elements, URLs, load states, timing
  • State/Information: Element state, attributes, bounding boxes
  • Visuals: Page and element screenshots
  • JavaScript Evaluation: Execute arbitrary JS (use with caution)

Installation

1. Install Dependencies:

   pip install "fastmcp>=2.0.0" playwright
   

2. Install Playwright Browsers:

   playwright install chromium
   

Usage

Running the Server

use fastmcp CLI:

fastmcp run main.py --transport sse --port 8001

Run the client script:

python client_example.py

Tool Reference

Page Management

Navigation

Content Retrieval

Interaction

Waiting

State and Information

Visuals

JavaScript

Security Notes

The playwright_evaluate and playwright_execute_javascript tools are powerful but potentially dangerous if the server is exposed publicly. Use these with caution or disable them if security is a concern.

Client Example

import asyncio
from fastmcp import Client

async def main():
    async with Client("stdio://python main.py") as client:
        # Open a new page and navigate to a website
        page_info = await client.call_tool("playwright_open_page", {"url": "https://example.com"})
        
        # Get the page title
        title = await client.call_tool("playwright_get_title", {})
        print(f"Page title: {title}")
        
        # Click a button
        await client.call_tool("playwright_click", {"selector": "button.submit"})
        
        # Take a screenshot
        screenshot = await client.call_tool("playwright_take_screenshot", {"full_page": True})

if __name__ == "__main__":
    asyncio.run(main())

License

This project is licensed under the MIT License - see the LICENSE file for details.