🌐 Browser MCP Server

用 Playwright + MCP 协议打造的浏览器自动化工具 任何支持 MCP 的 Agent（如 OpenClaw、Claude Desktop）都能直接用它控制浏览器 💎

---

功能概览

类别	工具	说明
🖥️ 浏览器控制	launch / close / status	启动/关闭浏览器
🧭 页面导航	navigate / back / forward / reload	页面跳转
📝 内容提取	get_text / get_links / get_inputs	提取文本/链接/表单
📸 截图	screenshot	全页/元素截图
🖱️ 交互操作	click / fill / select / check / hover	点击/填表/选择
🔍 搜索等待	search / wait_for_selector / wait_for_url / sleep	搜索/等待
📜 滚动	scroll	按方向/元素滚动

---

快速开始

安装

cd ~/workspace/browser-mcp-server
npm install
npx playwright install chromium   # 首次需要安装浏览器

方式一：直接运行测试

node test.js

方式二：启动 MCP Server（供 Agent 使用）

node src/index.js

Server 会以 Stdio 模式运行，等待 JSON-RPC 请求。

---

工具详细说明

🖥️ launch

启动浏览器。

{ "headless": true, "browserType": "chromium" }

• headless: true=后台（默认），false=显示 Chrome 窗口
• browserType: chromium / firefox / webkit

---

🧭 navigate

导航到 URL。

{ "url": "https://www.google.com", "waitUntil": "domcontentloaded" }

• waitUntil: domcontentloaded（默认）/ load / networkidle

---

📝 get_text

提取页面纯文本。

{ "selector": "article", "maxLength": 3000 }

• selector: CSS 选择器，不填则提取整页
• maxLength: 最大字符数，防止超长

---

📸 screenshot

截图。

{ "path": "./screenshot.png", "selector": ".chart", "fullPage": true }

• path: 保存路径
• selector: 截取指定元素
• fullPage: true=整页滚动截图

---

🖱️ click

点击元素。

{ "selector": "button.submit", "index": 0, "timeout": 5000 }

• index: 多个匹配时按序号（从 0 开始）

---

✏️ fill

向输入框填入文本。

{ "selector": "input[name='q']", "text": "Hello World", "pressEnter": true }

• pressEnter: 填入后自动按回车

---

📜 scroll

滚动页面。

{ "direction": "down", "amount": 500 }

• direction: down / up / left / right

---

在 OpenClaw 中使用

在 OpenClaw 的 skills/ 目录下创建一个 skill：

# Browser Automation MCP Skill

## 启动 MCP Server
command: node
args: ["src/index.js"]
cwd: /Users/sunxiaoxuan/workspace/browser-mcp-server
protocol: stdio

或者在代码中直接调用：

# Python 示例（通过 subprocess 调 MCP Server）
import subprocess, json

proc = subprocess.Popen(
    ['node', 'src/index.js'],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    cwd='/Users/sunxiaoxuan/workspace/browser-mcp-server'
)

# 发送 MCP 请求
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "launch",
        "arguments": {"headless": True}
    }
}

---

与 Siri 语音控制集成

配合 macOS 的 osascript 可以实现 Siri 语音控制浏览器！

# 例子："Hey Siri，打开 GitHub"
osascript -e 'tell application "System Events"
    keystroke "https://github.com" using command to activate
end tell'

配合 MCP Server 可以实现更复杂的语音指令：

"打开 GitHub，搜索 OpenAI 的最新项目，截一张图"

---

项目结构

browser-mcp-server/
├── package.json
├── README.md
├── test.js              # 快速测试脚本
└── src/
    ├── index.js         # MCP Server 主程序
    └── browser.js       # Playwright 浏览器管理

---

常见问题

Q: 报错 "Executable doesn't exist"

npx playwright install chromium

Q: 截图不完整（只截到可见区域） 设置 fullPage: true 截取整页

Q: 点击报错"元素不可见" 用 wait_for_selector 先等元素出现再操作

Q: 需要登录怎么办 先用 navigate 打开登录页，fill 填入账号密码，click 点击登录

---

庄英琪 💎 制作 | 基于 Playwright + MCP SDK