🚀 Playwright MCP 服务器

这个项目是一个使用模型上下文协议（MCP）提供 Playwright 网页内容检索功能的服务器，能够帮助用户轻松实现页面导航、内容检索、交互元素检测等操作，提升网页数据获取与操作的效率。

🚀 快速开始

本服务器可通过 Smithery 自动安装，也能手动安装。安装完成后，即可启动服务器并使用 MCP 工具进行网页操作。

✨ 主要特性

• 页面导航：可轻松导航到指定 URL。
• 全页面内容检索：能够检索整个页面的内容。
• 可见内容检索：获取当前页面的可见内容。
• 交互元素检测：检测页面上交互元素的位置信息。
• 鼠标操作模拟：支持鼠标移动、点击、滚动等操作。
• 测试用例回声功能：用于测试的回声工具。

📦 安装指南

使用 Smithery 安装

通过 Smithery 自动安装 Claude 桌面版的 Playwright MCP 服务器：

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

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

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

测试结构

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

实现特点

1. 内容检索：
   • 全页面内容检索
   • 可见内容-only 检索
   • 正确的 HTML 解析
2. 交互操作：
   • 交互元素检测及位置信息获取
   • 鼠标操作模拟（移动、点击、滚动）
   • 拖放支持
3. 错误处理：
   • 正确的导航错误处理
   • 超时处理
   • 无效 URL 检测
4. 灵活性配置：
   • 无头/有头模式选择
   • 自定义用户代理
   • 视口大小设置

📄 许可证

本项目使用 ISC 协议。

⚠️ 重要提示

使用 MCP 服务器前需设置环境变量，遵守相关网站的服务条款，确保安全合规地使用该工具。