PlayMCP

🚀 PlayMCP浏览器自动化服务器

PlayMCP是一个全面的MCP（模型上下文协议）服务器，它借助Playwright实现浏览器自动化。该服务器为网页数据抓取、测试和自动化操作提供了强大的工具。

✨ 主要特性

核心浏览器控制

• openBrowser - 启动一个新的浏览器实例，支持可选的无头模式
• navigate - 导航到任意URL
• click - 使用CSS选择器点击元素
• type - 在输入字段中输入文本
• moveMouse - 将鼠标移动到指定坐标
• scroll - 按指定量滚动页面
• screenshot - 对页面、视口或特定元素进行截图
• closeBrowser - 关闭浏览器实例

页面内容提取

• getPageSource - 获取完整的HTML源代码
• getPageText - 获取文本内容（去除HTML标签）
• getPageTitle - 获取页面标题
• getPageUrl - 获取当前URL
• getScripts - 从页面提取所有JavaScript代码
• getStylesheets - 提取所有CSS样式表
• getMetaTags - 获取所有带有属性的元标签
• getLinks - 获取所有带有href、文本和标题的链接
• getImages - 获取所有带有src、alt和尺寸的图像
• getForms - 获取所有带有字段和属性的表单
• getElementContent - 获取特定元素的HTML和文本内容

高级功能

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

📋 可用工具参考

📦 安装指南

完整安装步骤

1. 前提条件

   • Node.js 16+（从 nodejs.org 下载）
   • Git（用于克隆仓库）

2. 克隆并设置

   git clone 
   cd PlayMCP
   npm install
   npm run build
   

3. 安装Playwright浏览器

   npx playwright install
   

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

4. 验证安装

   npm run start
   

   如果一切正常，你应该会看到 "Browser Automation MCP Server starting..."。

快速安装

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": "使用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 Code GitHub Copilot集成

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

配置示例

Claude桌面版（config.json位置）：

• Windows: %APPDATA%\Claude\config.json
• macOS: ~/Library/Application Support/Claude/config.json
• Linux: ~/.config/Claude/config.json

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

完整配置示例：

{
"mcpServers": {
"playmcp-browser": {
"type": "stdio",
"command": "node",
"args": ["/Users/username/PlayMCP/dist/server.js"],
"description": "使用Playwright进行浏览器自动化"
}
}
}

工具使用示例

基础用法

// 打开浏览器并导航
await openBrowser({ headless: false, debug: true })
await navigate({ url: "https://example.com" })

// 提取内容
const title = await getPageTitle()
const links = await getLinks()
const forms = await getForms()

高级用法

// 表单自动化
// 填写表单
await click({ selector: "#login-button" })
await type({ selector: "#username", text: "user@example.com" })
await type({ selector: "#password", text: "password123" })
await click({ selector: "#submit" })

// 页面交互
// 滚动和交互
await scroll({ x: 0, y: 500 })
await moveMouse({ x: 100, y: 200 })
await click({ selector: ".dropdown-menu" })

// 高级JavaScript执行
// 运行自定义JavaScript
await executeJavaScript({
script: "document.querySelectorAll('h1').length"
})

// 修改页面内容
await executeJavaScript({
script: "document.body.style.backgroundColor = 'lightblue'"
})

// 提取复杂数据
await executeJavaScript({
script: `
Array.from(document.querySelectorAll('article')).map(article => ({
title: article.querySelector('h2')?.textContent,
summary: article.querySelector('p')?.textContent
}))
`
})

// 截图和文档记录
// 进行截图
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
   

2. 添加到你的MCP客户端配置

3. 开始自动化操作：

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

📚 详细文档

开发相关

• src/server.ts - 主要的MCP服务器实现
• src/controllers/playwright.ts - Playwright浏览器控制器
• src/mcp/ - MCP协议实现
• src/types/ - TypeScript类型定义

系统要求

依赖项

故障排除

常见问题

1. “Browser not initialized” 错误

   • 确保在其他浏览器操作之前调用 openBrowser
   • 检查Node.js版本是否为16或更高

2. Playwright安装失败

   # 尝试手动安装浏览器
   npx playwright install chromium
   # 或安装所有浏览器
   npx playwright install
   

3. Linux/macOS上的权限错误

   # 确保脚本可执行
   chmod +x dist/server.js
   

4. MCP配置中的路径问题

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

5. 浏览器崩溃或超时

   • 尝试以 headless: false 模式运行进行调试
   • 如果运行多个浏览器实例，增加系统内存
   • 检查防病毒软件是否阻止了浏览器进程

测试安装

# 直接测试服务器
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node ./dist/server.js

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

📄 许可证

本项目采用MIT许可证。