Arch1Panel/apps/playwright-mcp/README.md

Playwright MCP

Playwright MCP 是一个基于模型上下文协议 (MCP) 的服务器，它使用 Playwright 提供浏览器自动化功能。该服务器让大语言模型 (LLM) 能够通过结构化的可访问性快照与网页交互，而无需使用截图或视觉调优模型。

✨ 核心特性

• 🚀 快速轻量：使用 Microsoft 官方 MCP 镜像，预配置完整
• 🤖 LLM 友好：无需视觉模型，完全基于结构化数据操作
• 🎯 确定性工具应用：避免基于截图方法常见的模糊性
• 🌐 多浏览器支持：支持 Chromium、Firefox 和 WebKit
• 🔧 高度可配置：支持多种配置选项和运行模式
• 📦 官方镜像：使用 mcr.microsoft.com/playwright/mcp 官方镜像

📋 系统要求

• Node.js 18 或更新版本
• Docker 环境
• 1Panel 控制面板

🚀 快速开始

1Panel 部署

1. 在 1Panel 应用商店中搜索 "Playwright MCP"

2. 点击安装并配置以下参数：

   • 端口：服务访问端口（默认：8931）
   • 浏览器类型：选择 Chromium、Firefox 或 WebKit
   • 无头模式：是否启用无头模式运行
   • 视窗大小：浏览器视窗尺寸（格式：宽度,高度）
   • 用户代理：自定义浏览器用户代理字符串

3. 点击确认安装

访问服务

安装完成后，您可以通过以下方式访问：

• HTTP 端点：http://your-server-ip:port/mcp
• 健康检查：http://your-server-ip:port/mcp

⚙️ 配置说明

浏览器类型

• Chromium：推荐选择，兼容性最佳
• Firefox：Gecko 引擎，适合特定测试需求
• WebKit：Safari 内核，适合 Apple 生态测试

运行模式

• 有头模式：显示浏览器界面，适合调试
• 无头模式：后台运行，适合生产环境，性能更佳

视窗配置

• 格式：宽度,高度（如：1920,1080）
• 影响页面渲染和响应式布局
• 建议使用常见分辨率

🔌 MCP 客户端集成

VS Code

{
  "mcpServers": {
    "playwright": {
      "url": "http://your-server:8931/mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "playwright": {
      "url": "http://your-server:8931/mcp"
    }
  }
}

📊 性能优化

• 启用无头模式可减少资源消耗
• 选择合适的视窗大小避免不必要的渲染
• 定期清理用户数据目录
• 监控容器资源使用情况

🐛 故障排除

常见问题

1. 服务无法启动

   • 检查端口是否被占用
   • 确认 Docker 容器状态
   • 查看容器日志

2. 浏览器启动失败

   • 验证浏览器类型配置
   • 检查系统资源是否充足
   • 确认依赖安装完成

3. 连接问题

   • 检查防火墙设置
   • 验证网络配置
   • 确认端口映射正确

日志查看

# 查看容器日志
docker logs playwright-mcp

# 实时跟踪日志
docker logs -f playwright-mcp

🔗 相关链接

• 官方项目
• Playwright 文档
• MCP 协议规范
• 1Panel 文档

📄 许可证

本项目遵循原项目的开源许可证。详细信息请参考 官方仓库。

🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进这个应用配置。