Back to Details

browsing-with-playwright

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Browser Automation

浏览器自动化

Automate browser interactions via Playwright MCP server.
通过Playwright MCP服务器实现浏览器交互自动化。

Server Lifecycle

服务器生命周期

Start Server

启动服务器

bash
undefined
bash
undefined

Using helper script (recommended)

使用辅助脚本（推荐）

bash scripts/start-server.sh
bash scripts/start-server.sh

Or manually

或手动启动

npx @playwright/mcp@latest --port 8808 --shared-browser-context &
undefined
npx @playwright/mcp@latest --port 8808 --shared-browser-context &
undefined

Stop Server

停止服务器

bash
undefined
bash
undefined

Using helper script (closes browser first)

使用辅助脚本（先关闭浏览器）

bash scripts/stop-server.sh
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"
undefined
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_close -p '{}' pkill -f "@playwright/mcp"
undefined

When to Stop

何时停止服务器

  • End of task: Stop when browser work is complete
  • Long sessions: Keep running if doing multiple browser tasks
  • Errors: Stop and restart if browser becomes unresponsive
Important: The 
--shared-browser-context
flag is required to maintain browser state across multiple mcp-client.py calls. Without it, each call gets a fresh browser context.
  • 任务结束时：浏览器操作完成后停止
  • 长会话场景：若需执行多个浏览器任务，保持服务器运行
  • 出现错误时：若浏览器无响应，停止并重启服务器
重要提示：需要
--shared-browser-context
参数来在多次mcp-client.py调用之间保持浏览器状态。如果不使用该参数，每次调用都会创建一个全新的浏览器上下文。

Quick Reference

快速参考

Navigation

导航操作

bash
undefined
bash
undefined

Go to URL

访问指定URL

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate
-p '{"url": "https://example.com"}'
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 '{}'
undefined
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate_back -p '{}'
undefined

Get Page State

获取页面状态

bash
undefined
bash
undefined

Accessibility snapshot (returns element refs for clicking/typing)

可访问性快照（返回用于点击/输入的元素引用）

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_snapshot -p '{}'
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}'
undefined
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_take_screenshot
-p '{"type": "png", "fullPage": true}'
undefined

Interact with Elements

元素交互

Use 
ref
from snapshot output to target elements:
bash
undefined
使用快照输出中的
ref
来定位元素：
bash
undefined

Click element

点击元素

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_click
-p '{"element": "Submit button", "ref": "e42"}'
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}'
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": "john@example.com"}, {"ref": "e12", "value": "password123"}]}'
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_fill_form
-p '{"fields": [{"ref": "e10", "value": "john@example.com"}, {"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"]}'
undefined
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_select_option
-p '{"element": "Country dropdown", "ref": "e20", "values": ["US"]}'
undefined

Wait for Conditions

等待条件触发

bash
undefined
bash
undefined

Wait for text to appear

等待文本出现

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for
-p '{"text": "Success"}'
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}'
undefined
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for
-p '{"time": 2000}'
undefined

Execute JavaScript

执行JavaScript

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

Multi-Step Playwright Code

多步骤Playwright代码

For complex workflows, use 
browser_run_code
to run multiple actions in one call:
bash
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(); }"}'
Tip: Use 
browser_run_code
for complex multi-step operations that should be atomic (all-or-nothing).
对于复杂工作流，使用
browser_run_code
在单次调用中执行多个操作：
bash
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
。

Workflow: Form Submission

工作流：表单提交

  1. Navigate to page
  2. Get snapshot to find element refs
  3. Fill form fields using refs
  4. Click submit
  5. Wait for confirmation
  6. Screenshot result
  1. 导航至目标页面
  2. 获取快照以找到元素引用
  3. 使用元素引用填写表单字段
  4. 点击提交按钮
  5. 等待确认信息出现
  6. 对结果进行截图

Workflow: Data Extraction

工作流：数据提取

  1. Navigate to page
  2. Get snapshot (contains text content)
  3. Use browser_evaluate for complex extraction
  4. Process results
  1. 导航至目标页面
  2. 获取快照（包含文本内容）
  3. 使用browser_evaluate进行复杂数据提取
  4. 处理提取结果

Verification

验证步骤

Run: 
python3 scripts/verify.py
Expected: 
✓ Playwright MCP server running
运行：
python3 scripts/verify.py
预期结果：
✓ Playwright MCP server running

If Verification Fails

如果验证失败

  1. Run diagnostic: 
    pgrep -f "@playwright/mcp"
  2. Check: Server process running on port 8808
  3. Try: 
    bash scripts/start-server.sh
  4. Stop and report if still failing - do not proceed with downstream steps
  1. 运行诊断命令：
    pgrep -f "@playwright/mcp"
  2. 检查：服务器进程是否在8808端口运行
  3. 尝试重新启动：
    bash scripts/start-server.sh
  4. 如果仍失败，请停止操作并上报 - 不要继续后续步骤

Tool Reference

工具参考

See references/playwright-tools.md for complete tool documentation.
完整工具文档请查看references/playwright-tools.md。

Troubleshooting

故障排除

IssueSolution
Element not foundRun browser_snapshot first to get current refs
Click failsTry browser_hover first, then click
Form not submittingUse 
"submit": true
with browser_type
Page not loadingIncrease wait time or use browser_wait_for
Server not respondingStop and restart: 
bash scripts/stop-server.sh && bash scripts/start-server.sh
问题解决方案
未找到元素先运行browser_snapshot获取当前元素引用
点击操作失败先尝试browser_hover，再执行点击
表单未提交在browser_type中使用
"submit": true
参数
页面加载失败增加等待时长或使用browser_wait_for
服务器无响应停止并重启：
bash scripts/stop-server.sh && bash scripts/start-server.sh