Playwright MCP on Render

把微软官方 @playwright/mcp 部署到 Render，得到一个公网可访问的 MCP URL，用于 Cursor / Cline / Claude / VS Code 等客户端的 streamable_http / http / sse 方式连接。

当前版本组合：

• Docker 基础镜像：mcr.microsoft.com/playwright:v1.62.1-noble
• MCP 包：@playwright/mcp@0.0.79
• Node.js：基础镜像内置

1. 文件结构

playwright-mcp-render/
├── Dockerfile
├── package.json
├── auth-proxy.js
├── render.yaml
├── .dockerignore
└── README.md

2. 一键部署到 Render

方法 A：Blueprint（推荐）

1. 新建一个 GitHub 仓库，例如 playwright-mcp-render。
2. 把本项目所有文件 push 到仓库根目录。
3. 打开 Render：New + → Blueprint。
4. 选择这个 GitHub 仓库。
5. Render 会读取 render.yaml 并创建 Web Service。
6. 等待部署完成，得到类似：

https://playwright-mcp-render-xxxx.onrender.com

方法 B：手动创建 Web Service

1. Render → New + → Web Service。
2. 选择 GitHub 仓库。
3. Runtime 选 Docker。
4. Dockerfile path 填：./Dockerfile。
5. Health Check Path 填：/healthz。
6. Environment 里添加：

Key	Value	说明
MCP_TOKEN	生成一个强密码	开启公网鉴权，强烈建议
MCP_INTERNAL_PORT	8932	内部 MCP 服务端口
MCP_EXTRA_ARGS	--isolated	可选，传给 playwright-mcp 的额外参数

7. Deploy。

3. MCP URL 怎么填

部署后你的根地址假设是：

https://playwright-mcp-render-xxxx.onrender.com

优先尝试 Streamable HTTP 端点：

https://playwright-mcp-render-xxxx.onrender.com/mcp

如果客户端连接失败，再试旧 SSE 端点：

https://playwright-mcp-render-xxxx.onrender.com/sse

不同 MCP 客户端对 streamable_http、http、sse 命名不完全一致。Playwright MCP 新版本通常支持 /mcp，老式客户端可能要 /sse。

4. 鉴权方式

本项目默认通过 MCP_TOKEN 开启鉴权。推荐客户端请求头：

Authorization: Bearer 你的_MCP_TOKEN

如果你的 MCP 客户端不支持自定义请求头，可以临时用 query token：

https://playwright-mcp-render-xxxx.onrender.com/mcp?token=你的_MCP_TOKEN

或：

https://playwright-mcp-render-xxxx.onrender.com/sse?token=你的_MCP_TOKEN

注意：query token 可能出现在日志、浏览器历史、分享链接里，安全性不如 Authorization header。

5. 客户端配置示例

Cursor

如果支持请求头：

{
  "mcpServers": {
    "playwright-render": {
      "type": "streamableHttp",
      "url": "https://playwright-mcp-render-xxxx.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer 你的_MCP_TOKEN"
      }
    }
  }
}

如果不支持 headers：

{
  "mcpServers": {
    "playwright-render": {
      "type": "streamableHttp",
      "url": "https://playwright-mcp-render-xxxx.onrender.com/mcp?token=你的_MCP_TOKEN"
    }
  }
}

Cline

{
  "mcpServers": {
    "playwright-render": {
      "type": "streamableHttp",
      "url": "https://playwright-mcp-render-xxxx.onrender.com/mcp?token=你的_MCP_TOKEN"
    }
  }
}

Claude / VS Code

一般填 URL 型 MCP：

https://playwright-mcp-render-xxxx.onrender.com/mcp?token=你的_MCP_TOKEN

如果报 transport 不兼容，把路径换成：

https://playwright-mcp-render-xxxx.onrender.com/sse?token=你的_MCP_TOKEN

6. 本地测试

docker build -t playwright-mcp-render .
docker run --rm -p 8931:8931 -e MCP_TOKEN=dev-token playwright-mcp-render

健康检查：

curl http://localhost:8931/healthz

测试 MCP 端点是否有响应：

curl -i http://localhost:8931/mcp -H "Authorization: Bearer dev-token"
curl -i http://localhost:8931/sse -H "Authorization: Bearer dev-token"

看到非 401 响应，就说明鉴权和代理通了。MCP 正常握手通常要由 MCP 客户端发 JSON-RPC 请求完成。

7. 常用环境变量

变量	默认值	说明
PORT	8931	Render 注入的公网监听端口
MCP_TOKEN	空	设置后启用鉴权代理
MCP_INTERNAL_PORT	8932	鉴权代理后面的内部 MCP 端口
MCP_EXTRA_ARGS	空	额外传给 playwright-mcp 的参数

例如：

MCP_EXTRA_ARGS=--isolated --browser=chromium

可用参数例子：

参数	作用
--headless	无头浏览器，Render 必须用
--isolated	每次会话隔离，不复用登录态
--browser=chromium	指定 Chromium
--caps=network	开启网络相关工具（如版本支持）

8. 重要安全提醒

1. 不要裸奔公网。一定设置 MCP_TOKEN。
2. 不要让陌生人拿到你的 MCP URL。别人可以消耗你的 Render 资源并操控云端浏览器。
3. Playwright 官方 Docker 镜像主要用于测试/开发，不建议访问不可信网页。
4. Render 免费层容易休眠，首次连接可能要等 30 秒以上；浏览器自动化建议用 1GB+ 内存实例。

9. 排错

问题	处理
连接 401	token 不对，检查 Authorization: Bearer xxx 或 URL 里的 ?token=xxx
连接 404	/mcp 和 /sse 换着试
502 Bad gateway	Playwright MCP 还没启动完，等几秒重试；看 Render logs
浏览器启动失败	确认使用 Docker 镜像 mcr.microsoft.com/playwright:v1.62.1-noble
OOM / 崩溃	升级 Render 实例内存，浏览器自动化不适合太小内存

10. 最小无鉴权版本（不推荐）

如果不设置 MCP_TOKEN，Dockerfile 会直接运行：

./node_modules/.bin/playwright-mcp --port $PORT --host 0.0.0.0 --headless

公网 URL 不需要 token，但非常不安全，只建议临时测试。