browsing-with-playwright

浏览器自动化

通过 Playwright MCP 服务自动化浏览器交互。

服务生命周期

启动服务

# Using helper script (recommended)
bash scripts/start-server.sh

# Or manually
npx @playwright/mcp@latest --port 8808 --shared-browser-context &

停止服务

# Using helper script (closes browser first)
bash scripts/stop-server.sh

# Or manually
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_close -p '{}'
pkill -f "@playwright/mcp"

何时停止

• 任务结束时：浏览器工作完成后停止
• 长时间会话：如果执行多个浏览器任务，则保持运行
• 错误：如果浏览器无响应，则停止并重启

重要： 需要 --shared-browser-context 标志才能在多次 mcp-client.py 调用之间保持浏览器状态。没有它，每次调用都会获得全新的浏览器上下文。

快速参考

导航

# Go to URL
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate \
  -p '{"url": "https://example.com"}'

# Go back
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate_back -p '{}'

获取页面状态

# Accessibility snapshot (returns element refs for clicking/typing)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_snapshot -p '{}'

# Screenshot
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_take_screenshot \
  -p '{"type": "png", "fullPage": true}'

与元素交互

使用快照输出中的 ref 来定位元素：

# Click element
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_click \
  -p '{"element": "Submit button", "ref": "e42"}'

# Type text
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_type \
  -p '{"element": "Search input", "ref": "e15", "text": "hello world", "submit": true}'

# Fill form (multiple fields)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_fill_form \
  -p '{"fields": [{"ref": "e10", "value": "[email protected]"}, {"ref": "e12", "value": "password123"}]}'

# Select dropdown
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_select_option \
  -p '{"element": "Country dropdown", "ref": "e20", "values": ["US"]}'

等待条件

# Wait for text to appear
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"text": "Success"}'

# Wait for time (ms)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"time": 2000}'

执行 JavaScript

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_evaluate \
  -p '{"function": "return document.title"}'

多步 Playwright 代码

对于复杂的工作流，使用 browser_run_code 在一次调用中运行多个操作：

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_run_code \
  -p '{"code": "async (page) => { await page.goto(\"https://example.com\"); await page.click(\"text=Learn more\"); return await page.title(); }"}'

提示： 对于应具有原子性（全有或全无）的复杂多步操作，请使用 browser_run_code。

工作流：表单提交

1. 导航到页面
2. 获取快照以查找元素 ref
3. 使用 ref 填写表单字段
4. 点击提交
5. 等待确认
6. 截图结果

工作流：数据提取

1. 导航到页面
2. 获取快照（包含文本内容）
3. 使用 browser_evaluate 进行复杂提取
4. 处理结果

验证

运行：python3 scripts/verify.py

预期：✓ Playwright MCP server running

如果验证失败

1. 运行诊断：pgrep -f "@playwright/mcp"
2. 检查：服务进程是否在端口 8808 上运行
3. 尝试：bash scripts/start-server.sh
4. 如果仍然失败，停止并报告 - 不要继续执行后续步骤

工具参考

完整的工具文档请参见 references/playwright-tools.md。

故障排查

问题	解决方案
未找到元素	先运行 browser_snapshot 以获取当前 ref
点击失败	先尝试 browser_hover，然后再点击
表单未提交	配合 browser_type 使用 "submit": true
页面未加载	增加等待时间或使用 browser_wait_for
服务无响应	停止并重启：bash scripts/stop-server.sh && bash scripts/start-server.sh