PlayMCP Browser Automation Server

PlayMCP浏览器自动化服务器

使用Playwright实现浏览器自动化的综合MCP（模型上下文协议）服务器。此服务器提供 38个强大的工具 用于网络抓取、测试和自动化。

特性

🚀 核心浏览器自动化 （21工具）

• 导航: navigate, goForward, goBack （通过滚动）
• 交互: click, type, hover, dragAndDrop, selectOption
• 鼠标控制: moveMouse, mouseMove, mouseClick, mouseDrag
• 键盘: pressKey
• 等待: waitForText, waitForSelector
• 截图: screenshot, takeScreenshot （增强）
• 页面信息: getPageSource, getPageText, getPageTitle, getPageUrl
• 元素分析: getElementContent, getElementHierarchy
• 脚本和样式: getScripts, getStylesheets, getMetaTags

🔍 高级数据提取 （7工具）

• 链接和图片: getLinks, getImages
• 表单: getForms
• 控制台监控: getConsoleMessages
• 网络监控: getNetworkRequests
• JavaScript执行: executeJavaScript, evaluateWithReturn

📁 文件操作 （2个工具）

• 文件上传: uploadFiles
• 对话框处理: handleDialog

⚙️ 浏览器管理 （8工具）

• 浏览器控件: openBrowser, closeBrowser
• 视口管理: resize
• 页面操作: scroll （通过反馈增强）
• 元素层次结构：深度DOM分析，深度可配置
• 增强的屏幕截图：整页、特定元素、自定义路径
• 鼠标坐标：像素完美的鼠标控制
• 等待条件：智能等待元素和文本

快速开始

安装

# Clone the repository
git clone https://github.com/jomon003/PlayMCP.git
cd PlayMCP

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
npm test

基本用法

// Start the server
node ./dist/server.js

// Send MCP commands via JSON-RPC
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

工具类别

🎯 导航与交互

• 导航：转到任何URL
• goForward：在浏览器历史记录中向前导航
• 点击：使用智能选择器分辨率单击元素
• 类型：使用逼真的键盘模拟键入文本
• 悬停：将鼠标悬停在工具提示和交互的元素上
• 拖放：在位置之间拖动元素
• select选项：从下拉菜单和多选中选择选项
• 按键：发送特定键盘键（Enter、Escape等）

⏱️ 智能等待

• waitForText：等待特定文本出现
• waitForSelector：等待元素加载
• 内置超时和错误处理

🖱️ 精确的鼠标控制

• mouse移动：移动到精确坐标
• 鼠标点击：单击特定像素
• 鼠标拖动：在坐标点之间拖动
• 移动鼠标：增强鼠标定位

📊 数据提取

• getElementHierarchy：深度DOM结构分析
• 获取控制台消息：监视浏览器控制台输出
• getNetworkRequests：跟踪HTTP请求和响应
• getLinks：提取包含元数据的所有页面链接
• 获取图片：获取所有具有属性的图像
• getForms：分析表单结构和字段

🎬 视觉与媒体

• 截图：基本屏幕截图
• take截图：高级屏幕截图（整页、元素、自定义路径）
• 调整大小：控制视口尺寸

📁 文件和对话框操作

• uploadFiles：处理文件输入上传
• handleDialog：管理警报、确认和提示

⚙️ JavaScript执行

• 执行JavaScript：运行JavaScript代码
• 使用Return进行评估：使用返回值执行JS

核心浏览器控件

• 打开浏览器 -启动一个具有可选无头模式的新浏览器实例
• 导航 -导航到任何URL
• 点击 -使用CSS选择器单击元素
• 类型 -在输入框中键入文本
• 移动鼠标 -将鼠标移动到特定坐标
• 滚动 -通过增强的反馈和平滑滚动支持按指定数量滚动页面
• 截图 -对页面、视口或特定元素进行截图
• 关闭浏览器 -关闭浏览器实例

页面内容提取

• getPageSource -获取完整的HTML源代码
• 获取页面文本 -获取文本内容（去除HTML）
• getPageTitle -获取页面标题
• 获取页面URL -获取当前URL
• getScripts -从页面中提取所有JavaScript代码
• getStylesheets -提取所有CSS样式表
• getMetaTags -获取所有元标签及其属性
• getLinks -获取包含href、文本和标题的所有链接
• 获取图片 -获取所有具有src、alt和维度的图像
• getForms -获取所有表单及其字段和属性
• getElementContent -获取特定元素的HTML和文本内容
• getElementHierarchy -获取具有父子关系的分层DOM结构

高性能

• 执行JavaScript -在页面上执行任意JavaScript代码并返回结果

可用工具参考

安装

完成安装步骤

1. 先决条件

- Node.js 16+（从下载 ) - Git（用于克隆存储库）

1. 克隆和设置

   git clone 
   cd PlayMCP
   npm install
   npm run build

1. 安装Playwright浏览器

   npx playwright install

这将下载必要的浏览器二进制文件（Chromium、Firefox、Safari）。

1. 验证安装

   npm run start

如果一切正常，您应该看到“浏览器自动化MCP服务器正在启动…”。

快速安装

git clone 
cd PlayMCP
npm install && npm run build && npx playwright install

用法

作为MCP服务器

添加到MCP配置文件中：

标准MCP配置：

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/server.js"],
      "cwd": "/path/to/PlayMCP",
      "description": "Browser automation server using Playwright"
    }
  }
}

替代配置（适用于VS Code GitHub Copilot）：

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/PlayMCP/dist/server.js"]
    }
  }
}

对于Windows用户：

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\PlayMCP\\dist\\server.js"]
    }
  }
}

VS代码GitHub副本集成

此MCP服务器与VS Code GitHub Copilot完全兼容。将上述配置添加到MCP设置后，您可以直接在VS Code中使用所有浏览器自动化工具。

配置示例

克劳德桌面（config.json位置）：

• 窗户： %APPDATA%\Claude\config.json
• macOS： ~/Library/Application Support/Claude/config.json
• Linux： ~/.config/Claude/config.json

VS代码MCP扩展： 添加到您的VS Code settings.json或MCP配置文件中。

完整配置示例：

{
  "mcpServers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/username/PlayMCP/dist/server.js"],
      "description": "Browser automation with Playwright"
    }
  }
}

工具示例

基本Web抓取：

// Open browser and navigate
await openBrowser({ headless: false, debug: true })
await navigate({ url: "https://example.com" })

// Extract content
const title = await getPageTitle()
const links = await getLinks()
const forms = await getForms()

表单自动化：

// Fill out a form
await click({ selector: "#login-button" })
await type({ selector: "#username", text: "user@example.com" })
await type({ selector: "#password", text: "password123" })
await click({ selector: "#submit" })

页面交互：

// Enhanced scrolling with feedback
await scroll({ x: 0, y: 500, smooth: false })
// Returns: { before: {x: 0, y: 0}, after: {x: 0, y: 500}, scrolled: {x: 0, y: 500} }

// Smooth scrolling
await scroll({ x: 0, y: 300, smooth: true })

// Mouse interaction
await moveMouse({ x: 100, y: 200 })
await click({ selector: ".dropdown-menu" })

DOM结构分析：

// Get page hierarchy (3 levels deep)
await getElementHierarchy({ maxDepth: 3 })

// Get detailed hierarchy with text and attributes
await getElementHierarchy({ 
  selector: "#main-content", 
  maxDepth: -1, 
  includeText: true, 
  includeAttributes: true 
})

// Get basic structure of a specific section
await getElementHierarchy({ selector: ".sidebar", maxDepth: 2 })

高级JavaScript执行：

// Run custom JavaScript
await executeJavaScript({ 
  script: "document.querySelectorAll('h1').length" 
})

// Modify page content
await executeJavaScript({ 
  script: "document.body.style.backgroundColor = 'lightblue'" 
})

// Extract complex data
await executeJavaScript({ 
  script: `
    Array.from(document.querySelectorAll('article')).map(article => ({
      title: article.querySelector('h2')?.textContent,
      summary: article.querySelector('p')?.textContent
    }))
  `
})

屏幕截图和文件：

// Take screenshots
await screenshot({ path: "./full-page.png", type: "page" })
await screenshot({ path: "./element.png", type: "element", selector: "#main-content" })

快速开始

1. 安装和设置：

   git clone  && cd PlayMCP
   npm install && npm run build && npx playwright install

1. 添加到MCP客户端配置

1. 开始自动化：

   await openBrowser({ debug: true })
   await navigate({ url: "https://news.ycombinator.com" })
   const links = await getLinks()
   console.log(`Found ${links.length} links`)

   // Analyze page structure
   const hierarchy = await getElementHierarchy({ maxDepth: 2 })
   console.log('Page structure:', hierarchy)

发展

• src/server.ts -主MCP服务器实现
• src/控制器/剧作家.ts -Playwright浏览器控制器
• src/mcp/ -MCP协议实现
• src/类型/ -TypeScript类型定义

需求

系统要求

• Node.js 16+ （推荐LTS版本）
• 操作系统： Windows、macOS或Linux
• 内存： 至少2GB RAM（建议大量使用时使用4GB以上）
• 磁盘空间： 约500MB用于浏览器二进制文件和依赖项

依赖项

• 剧作家： 处理浏览器自动化（自动安装）
• TypeScript： 用于编译（开发依赖性）
• 浏览器二进制文件： 通过下载 npx playwright install

故障排除

常见问题

1. “浏览器未初始化”错误

- 一定要打电话 openBrowser 在其他浏览器操作之前 - 检查Node.js版本是否为16或更高

1. 剧作家安装失败

   # Try manual browser installation
   npx playwright install chromium
   # Or install all browsers
   npx playwright install

1. Linux/macOS上的权限错误

   # Make sure the script is executable
   chmod +x dist/server.js

1. MCP配置中的路径问题

- 在配置中使用绝对路径 - 在Windows上，使用双反斜杠： C:\\path\\to\\PlayMCP\\dist\\server.js - 验证路径是否存在： node /path/to/PlayMCP/dist/server.js

1. 浏览器崩溃或超时

- 试着用 headless: false 用于调试 - 如果运行多个浏览器实例，请增加系统内存 - 检查防病毒软件是否阻止浏览器进程

测试您的安装

# Test the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node ./dist/server.js

您应该看到一个列出所有可用工具的JSON响应。

许可证

MIT许可证