playwright-mcp-server

🚀 Playwright MCP 服务器

这个项目是一个使用 Model Context Protocol (MCP) 提供 Playwright 网页内容检索功能的服务器，借助 Playwright 强大的自动化能力，构建了一个灵活且可扩展的平台，方便其他服务或模型调用其功能，对于需要进行网页自动化测试、数据抓取或其他类似任务的开发者来说十分实用。

English | 日本語

🚀 快速开始

本项目是一个借助 Model Context Protocol (MCP) 来提供 Playwright 网页内容检索功能的服务器。

✨ 主要特性

• 页面导航：可实现页面的导航操作。
• 整个页面内容检索：能够检索整个页面的内容。
• 可见内容检索：支持对当前可见内容进行检索。
• 交互元素检测：可以检测页面上的交互元素。
• 鼠标操作模拟：能模拟鼠标的移动、点击、滚动和拖放等操作。
• 测试用例回声功能：具备测试用例回声工具。

📦 安装指南

使用 Smithery 自动安装

通过 Smithery 可自动为 Claude Desktop 安装 Playwright MCP Server：

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

手动安装

npm install

💻 使用示例

启动服务器

npm run build
npm start

MCP 工具

以下工具可供使用：

1. navigate
   • 功能：导航到指定 URL。
   • 参数：{ url: string }
   • 返回：导航结果
2. get_all_content
   • 功能：检索整个页面的内容。
   • 参数：无
   • 返回：页面中的所有文本内容
3. get_visible_content
   • 功能：检索当前可见内容。
   • 参数：{ minVisiblePercentage?: number }
   • 返回：可见的文本内容
4. get_interactive_elements
   • 功能：获取交互元素的位置信息（按钮、链接等）。
   • 参数：无
   • 返回：页面上交互元素的坐标和边界信息
5. move_mouse
   • 功能：将鼠标指针移动到指定坐标。
   • 参数：{ x: number, y: number }
   • 返回：操作结果
6. mouse_click
   • 功能：在指定坐标执行鼠标点击。
   • 参数：{ x: number, y: number, button?: "left" | "right" | "middle", clickCount?: number }
   • 返回：点击操作结果
7. mouse_wheel
   • 功能：执行鼠标滚轮滚动。
   • 参数：{ deltaY: number, deltaX?: number }
   • 返回：滚动操作结果
8. drag_and_drop
   • 功能：执行拖放操作。
   • 参数：{ sourceX: number, sourceY: number, targetX: number, targetY: number }
   • 返回：拖放操作结果
9. echo
   • 功能：测试用例回声工具。
   • 参数：{ message: string }
   • 返回：发送的消息

📚 详细文档

开发

运行测试

# 运行所有测试
npm test

# 以 watch 模式运行测试
npm run test:watch

# 生成覆盖报告
npm run test:coverage

测试结构

• tools/*.test.ts：每个工具的功能测试
• mcp-server.test.ts：MCP 服务器的整体测试

实现特点

• 内容获取：能高效地检索页面内容，支持可见和不可见内容。
• 交互操作：可模拟鼠标移动、点击和滚动等用户操作。
• 错误处理：拥有完善的异常处理机制，确保服务器稳定运行。
• 配置灵活性：支持无头模式、自定义用户代理等配置选项。

⚠️ 重要提示

1. 需要设置必要的环境变量以确保服务器正常运行。
2. 要遵循目标网站的服务条款和使用规则。
3. 需保持合理的时间间隔发送请求，避免触发反爬机制。
4. 模拟鼠标操作时要注意频率控制，避免被误判为恶意攻击。