Playmcp

🚀 PlayMCP浏览器自动化服务器

PlayMCP是一个基于Playwright的综合性MCP（模型上下文协议）服务器，用于浏览器自动化。该服务器为网页抓取、测试和自动化提供了强大的工具。

🚀 快速开始

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

📦 安装指南

完整安装步骤

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": "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 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": "Browser automation with 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()

高级用法

// 运行自定义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
    }))
  `
})

📚 详细文档

可用工具参考

🔧 技术细节

开发文件结构

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