浏览器自动化服务器

Playwright MCP 服务器

一个使用Playwright提供浏览器自动化能力的模型上下文协议（MCP）服务器。该服务器可以在stdio模式（用于本地MCP客户端）和HTTP模式（用于在Render等平台上进行云部署）下运行。

特点/功能

• 全面的浏览器自动化30+个Playwright工具，涵盖所有主要浏览器自动化任务
• 全面导航控制导航、重新加载、返回/前进、处理URL和页面标题
• 元素交互点击、填写、选择下拉菜单、悬停、勾选/取消勾选复选框
• 键盘操作按键，以可自定义的延迟输入文本
• 元素检查获取文本、属性、可见性、启用状态、元素数量
• 等待与时机等待选择器，为动态内容设置超时
• 屏幕截图与PDF文件捕获全屏或视口截图，生成PDF文件
• Cookie管理获取、设置和删除cookie
• JavaScript 执行在浏览器上下文中运行自定义JavaScript
• 视口控制设置自定义视口大小以进行响应式测试
• 双模式在本地作为MCP标准输入输出服务器运行，或在云平台上作为HTTP API运行
• 安全API密钥认证和CORS支持，用于Web应用集成
• Docker 支持容器化，便于在Render上轻松部署

可用工具（30+个Playwright操作）

导航与页面控制

1. 导航 - 导航到一个URL

   • 参数： url (字符串)

2. 返回 - 在浏览器历史记录中返回

3. 继续前进 - 在浏览器历史记录中前进

4. 重新加载 - 重新加载当前页面

5. 获取网址 - 获取当前页面的URL

6. 获取标题 - 获取页面标题

元素交互

7. 点击 - 点击一个元素

   • 参数： selector (字符串)

8. 填充 - 填写表单字段

   • 参数： selector （字符串）， value （字符串）

9. 选择 - 从下拉菜单中选择一个选项

   • 参数： selector （字符串）， value (字符串)

10. 悬停 - 将鼠标悬停在元素上

    • 参数： selector (字符串)

11. 检查 - 勾选复选框/单选按钮

    • 参数： selector (字符串)

12. 取消勾选 - 取消选中复选框

    • 参数： selector （字符串）

键盘操作

13. 按压按键 - 按下一个键盘键

    • 参数： key （字符串）， selector （字符串，可选）

14. 文本类型 - 逐个字符输入文本

    • 参数： selector (字符串)， text （字符串）， delay （数字，可选）

元素信息

15. 获取文本 - 获取元素文本内容

    • 参数： selector (字符串)

16. 获取属性 - 获取元素属性值

    • 参数： selector （字符串）， attribute （字符串）

17. 获取内容 - 获取页面的HTML内容

18. 可见性（或“是否可见”） - 检查元素是否可见

    • 参数： selector （字符串）

19. is_enabled 的中文翻译是“是否启用” - 检查元素是否启用

    • 参数： selector （字符串）

20. 已选中 - 检查复选框/单选按钮是否被选中

    • 参数： selector (字符串)

21. 统计元素数量 - 统计匹配选择器的元素数量

    • 参数： selector (字符串)

等待与时机

22. 等待选择器（或：等待指定选择器） - 等待元素出现

    • 参数： selector (字符串)， timeout （数字，可选）

23. 等待超时 - 等待指定时间

    • 参数： timeout （数字，毫秒）

截图和PDF文件

24. 屏幕截图 - 截图

    • 参数： name （字符串，可选）， fullPage （布尔值，可选）

25. PDF（Portable Document Format，便携式文档格式） - 生成该页面的PDF文件

    • 参数： name （字符串，可选）

Cookies（网络小甜饼/浏览器cookie）

26. 获取cookies - 获取所有cookie

27. 设置cookie - 设置一个cookie

    • 参数： name (字符串)， value （字符串）， domain （可选）， path （可选）

28. 删除cookie - 删除所有cookie

JavaScript 执行

29. 评估 - 在浏览器上下文中执行JavaScript
    • 参数： script (字符串)

视口

30. 设置视口 - 设置浏览器视口大小
    • 参数： width （数字）， height （数字）

本地开发

先决条件

• Node.js 18 或更高版本
• npm 或 yarn

安装

npm install

构建

npm run build

本地运行（stdio 模式）

SERVER_MODE=stdio npm start

本地运行（HTTP 模式）

npm start
# Server will run on http://localhost:3000

部署到渲染环境

选项1：从GitHub部署（推荐）

1. 将你的代码推送到GitHub

   复制

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin <your-github-repo-url>
   git push -u origin main
   

2. 连接到渲染服务

   • 首选 渲染仪表板
   • 点击“新建”→“Web 服务”
   • 连接你的GitHub仓库
   • Render 将自动检测 render.yaml 配置

3. 部署

   • Render 将自动构建并部署您的服务
   • 该服务将在您的渲染URL上可用

选项2：使用render.yaml进行手动部署

1. 安装Render CLI （可选）

   复制

   npm install -g render-cli
   

2. 在Render上创建一个新的Web服务

   • 首选 渲染仪表盘
   • 点击“新建”→“Web 服务”
   • 选择“从Git部署”或“部署现有镜像”
   • 使用提供的配置方法进行设置 render.yaml

3. 配置详情 这个（或“该”） render.yaml 文件包含：

   • 基于Docker的部署
   • 健康检查端点位于 /health
   • 生产模式的环境变量
   • 已启用自动部署

测试您的部署

部署完成后，您可以测试您的渲染服务：

# Health check
curl https://your-app.onrender.com/health

# List available tools
curl https://your-app.onrender.com/tools

# Execute a tool (example: navigate)
curl -X POST https://your-app.onrender.com/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "navigate",
    "arguments": {
      "url": "https://example.com"
    }
  }'

# Take a screenshot
curl -X POST https://your-app.onrender.com/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "screenshot",
    "arguments": {
      "name": "example",
      "fullPage": true
    }
  }'

Web应用集成

好的！您的网络应用可以通过HTTP API调用与已部署的Playwright MCP服务器进行通信。服务器包括：

• CORS 支持配置允许的跨域请求来源
• API密钥认证使用API密钥身份验证保护您的终端节点
• JSON API适用于所有浏览器自动化工具的易用REST API

获取您的API密钥

在Render上部署后：

1. 前往您的渲染仪表板
2. 选择您的服务
3. 转到“环境”选项卡
4. 找到 API_KEY 变量（Render 自动生成安全密钥）
5. 将此密钥复制到您的网络应用中使用

从您的网页应用中拨打电话

JavaScript/Fetch 示例

const response = await fetch('https://your-app.onrender.com/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your-api-key-here'
  },
  body: JSON.stringify({
    tool: 'navigate',
    arguments: { url: 'https://example.com' }
  })
});

const result = await response.json();
console.log(result);

React 示例

const takeScreenshot = async (url: string) => {
  // First navigate
  await fetch('https://your-app.onrender.com/execute', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.REACT_APP_PLAYWRIGHT_API_KEY
    },
    body: JSON.stringify({
      tool: 'navigate',
      arguments: { url }
    })
  });

  // Then screenshot
  const response = await fetch('https://your-app.onrender.com/execute', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.REACT_APP_PLAYWRIGHT_API_KEY
    },
    body: JSON.stringify({
      tool: 'screenshot',
      arguments: { fullPage: true }
    })
  });

  const result = await response.json();
  const imageData = result.content.find(c => c.type === 'image')?.data;
  return `data:image/png;base64,${imageData}`;
};

看看 examples/ 包含完整集成示例的文件夹：

• web-app-integration.html - 独立HTML客户端
• javascript-example.js - Node.js/纯JS示例
• react-example.tsx - React 组件示例

API 端点（HTTP 模式）

获取 /health（即访问健康检查端点）

健康检查端点（无需认证）

回答：

{
  "status": "ok",
  "service": "playwright-mcp-server"
}

获取 /tools（或“访问 /tools”）

列出所有可用的工具（需要API密钥）

标题（或头部信息）：

X-API-Key: your-api-key-here

回应：

{
  "tools": [...]
}

POST /执行

执行一个工具（需要API密钥）

标题/头部信息：

Content-Type: application/json
X-API-Key: your-api-key-here

请求体：

{
  "tool": "navigate",
  "arguments": {
    "url": "https://example.com"
  }
}

回答：

{
  "content": [
    {
      "type": "text",
      "text": "Successfully navigated to https://example.com"
    }
  ]
}

环境变量

• SERVER_MODE设置为 http 对于HTTP服务器模式，或 stdio 对于MCP stdio模式（默认： http)
• PORTHTTP服务器的端口号（默认： 3000)
• NODE_ENV节点环境（默认： production)
• API_KEY认证用的API密钥（由Render自动生成，或手动设置）
• ALLOWED_ORIGINS用于CORS的允许来源的逗号分隔列表，或 * 对于所有（默认： *)
• PLAYWRIGHT_BROWSERS_PATHPlaywright 浏览器的路径（默认： /ms-playwright)

安全注意事项

• API密钥在生产环境中始终设置API密钥。使用时，Render会自动生成一个 generateValue: true
• **CORS（跨源资源共享）**对于生产，设置 ALLOWED_ORIGINS 针对您的特定领域（或域名），而不是 *
• HTTPSRender 默认提供 HTTPS，生产环境中始终使用 HTTPS 端点

Docker（注：Docker是一个用于开发、部署和运行应用程序的开源平台，可以实现应用的容器化）

构建Docker镜像

docker build -t playwright-mcp-server .

运行Docker容器

docker run -p 3000:3000 \
  -e SERVER_MODE=http \
  playwright-mcp-server

故障排除

浏览器无法启动

• 确保您已安装运行 Playwright 所需的系统依赖项
• 检查Chromium浏览器是否已正确安装
• 验证容器是否具有足够的内存（建议至少512MB）

渲染部署失败

• 在Render仪表板中检查构建日志
• 确保 render.yaml 位于根目录中
• 验证Dockerfile是否有效
• 检查环境变量是否已正确设置

健康检查失败

• 确保 /health 终端正在响应
• 检查 PORT 环境变量是否与 Render 预期的端口匹配
• 验证服务是否正在监听 0.0.0.0 不仅仅是 localhost

许可证

麻省理工学院（MIT）

做出贡献

欢迎贡献！请随时提交拉取请求。