Playwright MCP Server

🚀 Playwright MCP Server

English | 日本語

This project is a server that provides Playwright web content retrieval functionality using the Model Context Protocol (MCP).

🚀 Quick Start

This project is a server that uses the Model Context Protocol (MCP) to offer Playwright web content retrieval capabilities. It simplifies web automation tasks and provides a range of useful features.

✨ Features

• Page navigation
• Full page content retrieval
• Visible content retrieval
• Interactive element detection
• Mouse operation simulation
• Test case echo function

📦 Installation

Automatic Installation via Smithery

Automatically install the Playwright MCP Server for Claude Desktop through Smithery:

npx -y @smithery/cli install @showfive/playwright-mcp-server --client claude

Manual Installation

npm install

💻 Usage Examples

Start the Server

npm run build
npm start

MCP Tools

The following tools are available:

1. navigate
   • Navigate to the specified URL.
   • Parameters: { url: string }
   • Returns: Navigation result
2. get_all_content
   • Retrieve the entire page content.
   • Parameters: None
   • Returns: All text content on the page
3. get_visible_content
   • Retrieve the currently visible content.
   • Parameters: { minVisiblePercentage?: number }
   • Returns: Visible text content
4. get_interactive_elements
   • Get the position information of interactive elements (buttons, links, etc.).
   • Parameters: None
   • Returns: Coordinates and boundary information of interactive elements on the page
5. move_mouse
   • Move the mouse pointer to the specified coordinates.
   • Parameters: { x: number, y: number }
   • Returns: Operation result
6. mouse_click
   • Perform a mouse click at the specified coordinates.
   • Parameters: { x: number, y: number, button?: "left" | "right" | "middle", clickCount?: number }
   • Returns: Click operation result
7. mouse_wheel
   • Perform a mouse wheel scroll.
   • Parameters: { deltaY: number, deltaX?: number }
   • Returns: Scroll operation result
8. drag_and_drop
   • Perform a drag-and-drop operation.
   • Parameters: { sourceX: number, sourceY: number, targetX: number, targetY: number }
   • Returns: Drag-and-drop operation result
9. echo
   • Test case echo tool.
   • Parameters: { message: string }
   • Returns: Sent message

🔧 Technical Details

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

Test Structure

• tools/*.test.ts: Functional tests for each tool
• mcp-server.test.ts: Overall test of the MCP server

Implementation Features

• Content Retrieval: Efficiently retrieve page content, supporting both visible and invisible content.
• Interactive Operations: Simulate user operations such as mouse movement, clicks, and scrolling.
• Error Handling: A comprehensive exception handling mechanism ensures the stable operation of the server.
• Configuration Flexibility: Supports configuration options such as headless mode and custom user agents.

⚠️ Important Note

• Set the necessary environment variables to ensure the normal operation of the server.
• Comply with the terms of service and usage rules of the target website.
• Maintain a reasonable time interval when sending requests to avoid triggering anti - scraping mechanisms.
• Control the frequency when simulating mouse operations to avoid being misjudged as a malicious attack.

📚 Documentation

The Playwright MCP Server builds a flexible and extensible platform through the powerful automation capabilities of Playwright, making it convenient for other services or models to call its functions. It is a very useful tool for developers who need to perform web automation testing, data scraping, or other similar tasks.