Playwright Web Browser

🚀 Playwright MCP Server

English | 日本語

This project is a server that uses the Model Context Protocol (MCP) to provide Playwright web content retrieval functionality.

✨ Features

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

📦 Installation

Install via Smithery

Automatically install 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 }
   • Return value: Navigation result

2. get_all_content

   • Retrieve the content of the entire page.
   • Parameters: None
   • Return value: All text content on the page

3. get_visible_content

   • Retrieve the currently visible content.
   • Parameters: { minVisiblePercentage?: number }
   • Return value: Currently visible text content

4. get_interactive_elements

   • Get the position information of interactive elements (buttons, links, etc.).
   • Parameters: None
   • Return value: 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 }
   • Return value: Operation result

6. mouse_click

   • Perform a mouse click at the specified coordinates.
   • Parameters: { x: number, y: number, button?: "left" | "right" | "middle", clickCount?: number }
   • Return value: Result of the click operation

7. mouse_wheel

   • Perform mouse wheel scrolling.
   • Parameters: { deltaY: number, deltaX?: number }
   • Return value: Result of the scrolling operation

8. drag_and_drop

   • Perform a drag-and-drop operation.
   • Parameters: { sourceX: number, sourceY: number, targetX: number, targetY: number }
   • Return value: Result of the drag-and-drop operation

9. echo

   • Test case echo tool.
   • Parameters: { message: string }
   • Return value: Sent message

🔧 Technical Details

Run Tests

# Execute all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate a coverage report
npm run test:coverage

Test Structure

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

Implementation Features

1. Content Retrieval

   • Full-page content retrieval
   • Visible content-only retrieval
   • Correct HTML parsing

2. Interactive Operations

   • Interactive element detection and position information acquisition
   • Mouse operation simulation (movement, click, scroll)
   • Drag-and-drop support

3. Error Handling

   • Correct navigation error handling
   • Timeout handling
   • Invalid URL detection

4. Flexible Configuration

   • Choice between headless and headed modes
   • Custom user agent
   • Viewport size setting

📄 License

ISC

⚠️ Important Note

Ensure that the environment variables are correctly set before using the MCP server. When retrieving content using the target website's terms of service, please comply with the relevant regulations. Maintain an appropriate interval when sending multiple requests. When performing mouse operations, maintain an appropriate time interval to simulate real user interactions.