# 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. 文件结构

```text
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. 等待部署完成，得到类似：

```text
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 怎么填

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

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

优先尝试 Streamable HTTP 端点：

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

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

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

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

## 4. 鉴权方式

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

```text
Authorization: Bearer 你的_MCP_TOKEN
```

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

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

或：

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

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

## 5. 客户端配置示例

### Cursor

如果支持请求头：

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

如果不支持 headers：

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

### Cline

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

### Claude / VS Code

一般填 URL 型 MCP：

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

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

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

## 6. 本地测试

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

健康检查：

```bash
curl http://localhost:8931/healthz
```

测试 MCP 端点是否有响应：

```bash
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` 的参数 |

例如：

```text
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 会直接运行：

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

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