playwright mcp server

Local 2025-09-01 00:12:57 0
Browser Automation @showfive/playwright-mcp-server

Provides a server utilizing Model Context Protocol to enable human-like browser automation with Playwright, allowing control over browser actions such as navigation, element interaction, and scrolling.

smithery badge

English | 日本語

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

Features

  • Page navigation
  • Full page content retrieval
  • Visible content retrieval
  • Interactive elements detection
  • Mouse operation simulation
  • Echo functionality for testing

Installation

Installing via Smithery

To install Playwright MCP Server for Claude Desktop automatically via Smithery:

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

Manual Installation

npm install

Usage

Starting the Server

npm run build
npm start

MCP Tools

The following tools are available:

  1. navigate
  2. Navigate to a specified URL
  3. Arguments: { url: string }

  4. Returns: Navigation result

  5. get_all_content

  6. Retrieve content from the entire page
  7. Arguments: None

  8. Returns: All text content from the page

  9. get_visible_content

  10. Retrieve currently visible content
  11. Arguments: { minVisiblePercentage?: number }

  12. Returns: Visible text content

  13. get_interactive_elements

  14. Get position information of interactive elements (buttons, links, etc.) on the page
  15. Arguments: None

  16. Returns: Coordinates and boundary information of interactive elements

  17. move_mouse

  18. Move mouse cursor to specified coordinates
  19. Arguments: { x: number, y: number }

  20. Returns: Operation result

  21. mouse_click

  22. Execute mouse click at specified coordinates
  23. Arguments: { x: number, y: number, button?: "left" | "right" | "middle", clickCount?: number }

  24. Returns: Click operation result

  25. mouse_wheel

  26. Execute mouse wheel scrolling
  27. Arguments: { deltaY: number, deltaX?: number }

  28. Returns: Scroll operation result

  29. drag_and_drop

  30. Execute drag and drop operation
  31. Arguments: { sourceX: number, sourceY: number, targetX: number, targetY: number }

  32. Returns: Drag and drop operation result

  33. echo

  34. Echo tool for testing
  35. Arguments: { message: string }
  36. Returns: Sent message

Development

Running 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: Function tests for each tool
  • mcp-server.test.ts: MCP server function tests

Implementation Features

  1. Content Retrieval
  2. Full page content retrieval
  3. Visible content only retrieval

  4. Proper HTML parsing

  5. Interaction

  6. Detection and position information retrieval of interactive elements
  7. Mouse operation simulation (movement, clicks, scrolling)

  8. Drag and drop support

  9. Error Handling

  10. Proper navigation error handling
  11. Timeout processing

  12. Invalid URL detection

  13. Configuration Flexibility

  14. Headless/head mode selection
  15. Custom user agent
  16. Viewport size settings

Important Notes

  • Ensure necessary environment variables are set before using the MCP server
  • Follow the terms of service of target websites when retrieving web page content
  • Maintain appropriate intervals when sending multiple requests
  • When performing mouse operations, maintain appropriate intervals as they simulate actual user interactions

License

ISC