Playmcp

🚀 PlayMCP浏览器自动化服务器

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

🚀 快速开始

1. 安装并设置：

git clone <repo-url> && 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(`Found ${links.length} links`)

✨ 主要特性

核心浏览器控制

• 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代码并返回结果

📚 详细文档

可用工具参考

使用方式

作为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执行
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" })

🔧 技术细节

开发文件结构

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

系统要求

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

依赖项

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

🛠️ 故障排除

常见问题

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许可证。