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 <repository-url>
   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 <repository-url>
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 <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(`找到 ${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许可证。